One Identity Active Roles 7.4

How-To Guide
Copyright 2019 One Identity LLC.
ALL RIGHTS RESERVED.
This guide contains proprietary information protected by copyright. The software described in this guide 
is furnished under a software license or nondisclosure agreement. This software may be used or copied 
only in accordance with the terms of the applicable agreement. No part of this guide may be reproduced 
or transmitted in any form or by any means, electronic or mechanical, including photocopying and 
recording for any purpose other than the purchaser’s personal use without the written permission of 
One Identity LLC .
The information in this document is provided in connection with One Identity products. No license, 
express or implied, by estoppel or otherwise, to any intellectual property right is granted by this 
document or in connection with the sale of One Identity LLC products. EXCEPT AS SET FORTH IN THE 
TERMS AND CONDITIONS AS SPECIFIED IN THE LICENSE AGREEMENT FOR THIS PRODUCT, 
ONE IDENTITY ASSUMES NO LIABILITY WHATSOEVER AND DISCLAIMS ANY EXPRESS, IMPLIED OR 
STATUTORY WARRANTY RELATING TO ITS PRODUCTS INCLUDING, BUT NOT LIMITED TO, THE 
IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-
INFRINGEMENT. IN NO EVENT SHALL ONE IDENTITY BE LIABLE FOR ANY DIRECT, INDIRECT, 
CONSEQUENTIAL, PUNITIVE, SPECIAL OR INCIDENTAL DAMAGES (INCLUDING, WITHOUT 
LIMITATION, DAMAGES FOR LOSS OF PROFITS, BUSINESS INTERRUPTION OR LOSS OF 
INFORMATION) ARISING OUT OF THE USE OR INABILITY TO USE THIS DOCUMENT, EVEN IF 
ONE IDENTITY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. One Identity makes no 
representations or warranties with respect to the accuracy or completeness of the contents of this 
document and reserves the right to make changes to specifications and product descriptions at any 
time without notice. One Identity does not make any commitment to update the information 
contained in this document.
If you have any questions regarding your potential use of this material, contact:
One Identity LLC.
Attn: LEGAL Dept
4 Polaris Way
Aliso Viejo, CA 92656
Refer to our Web site (http://www.OneIdentity.com) for regional and international office information.
Patents
One Identity is proud of our advanced technology. Patents and pending patents may apply to this 
product. For the most current information about applicable patents for this product, please visit our 
website at http://www.OneIdentity.com/legal/patents.aspx.
Trademarks
One Identity and the One Identity logo are trademarks and registered trademarks of One Identity 
LLC. in the U.S.A. and other countries. For a complete list of One Identity trademarks, please visit 
our website at www.OneIdentity.com/legal.  All other trademarks are the property of their 
respective owners.
Legend

WARNING: A WARNING icon indicates a potential for property damage, personal

injury, or death.

CAUTION: A CAUTION icon indicates potential damage to hardware or loss of data if

instructions are not followed.

IMPORTANT, NOTE, TIP, MOBILE, or VIDEO: An information icon indicates supporting 
information.

Active Roles How-To Guide
Updated - December 2019
Version - 7.4
Contents

What’s New 1
What’s new in Active Roles 7.4 1
What’s new in Active Roles 7.3 2
What’s new in Active Roles from version 7.0 3

Changes to Setup and Installation 5

Changes to System requirements and Supported platforms 8

System Requirements 9
Ports Used by Active Roles 9

Required Permissions and Access 13

Product Licensing 17

Pre-Installation and Upgrade 18

Installing Active Roles Diagnostic Tools 18
Checking System Readiness 19

Clean Installation 20
Installing the Active Roles service 20
Installing the Web interface 21

Upgrade from Active Roles 6.9 22

Prerequisites for Active Roles 6.9 upgrade 22
Importing Change History 24

In-Place Upgrade from Active Roles 7.x 25

Synchronization Service 27
Capture Agent 29
Upgrade from Quick Connect 29
Limitations 30
Synchronization Service upgrade 30
Communication Ports 31

Starling Two-Factor Authentication 33

Active Roles 7.4 How-To Guide 3

Reports 34
How to configure Reports 34
Can Reports databases be re-used? 34

Customizations 36

Troubleshooting 37
Performance 37
Safe Mode 37
Error and Log resources 38
Active Roles Log Viewer 40

Replication 42

Understanding Management History 43

Considerations and best practices 43
Management History configuration 45

Service Account 47
Changing Active Roles service account credentials 47
Changing  Service account credentials for SQL database connection 47

About us 49
Contacting us 49
Technical support resources 49

Active Roles 7.4 How-To Guide 4

 1

What’s New

For detailed information about new features, see the Active Roles 7.4 What’s New Guide.

What’s new in Active Roles 7.4

This section provides a summary of the new features included in Active Roles  Version 7.4. 
For detailed information about new features, see the Active Roles 7.4 What’s New Guide.
Major new features in Active Roles Version 7.4:

 l Additional Hybrid Directory features:
 l Support for Office 365 Group CRUD activities.
 l Support for Office 365 roles and reporting for Office 365 users.
 l Support for Exchange Online Mailbox Properties for Office 365 users in 
Federated and Synchronized environment.
 l Support for provisioning objects in SaaS products.
 l Separate configuration and management history databases during installation or in-
place upgrade, confirming to Microsoft standards and best practices for replication.
 l Support for Azure AD Graph 1.6  for Active Roles Synchronization Services.
 l Use of Group Managed Service Account (gMSA) for Active Roles Service account.
 l Bulk attribute operations for multiple users.
 l Reset the password for multiple users at one time.
 l Solution Intelligence for Active Roles.
 l Log in to MMC interface through 2FA authentication.
 l Support for remote mailbox creation and modification. 
NOTE: The ‘Remote mailbox migration (RemoteMailbox.ps1)’ script has been 
provided as a sample script only, to illustrate the steps required, and should not 
be used as-is in a production situation without modification and enhancement.  
The use of security credentials within a script in clear text should never be 
considered appropriate or secure.  In testing this script, care and consideration 

Active Roles 7.4 How-To Guide

1
What’s New
 should be given to the authentication and use of credentials, and clear text 
credentials should not be left in the script once testing is complete.
For more details refer the KB article: 
https://support.oneidentity.com/kb/310525 .
 l Support for Federated authentication feature.
 l Support to provide product feedback from the Web Interface.

 
Enhancements

 l Support for the multiSubnetFailOver feature of MS SQL Server to maximize 
internal availability.
 l Support for Archive Mailbox-Exchange Online functionality. 
 l Support for the Security Identity Mappings functionality as available in Active 
Directory Users and Computers (ADUC) Snap-in.
 l  Workflow  enhancements  that  enable  you  to  add  Azure  or  Office  365  modules  in 
PowerShell  and  run  the  Office  365  services  such  as  Skype  for  Business,  Azure 
AD,  Azure  RM,  AZ,  and  Sharepoint  Powershell  scripts  within  existing  Active 
Roles  workflows.
 l Restrict MMC interface access to users, by enabling the MMC Interface access 
settings using the Configuration Center. By default, on installing Active Roles, all 
users are enabled to log in to the MMC interface. You can now enable the  MMC 
interface access setting to restrict users from accessing the MMC interface.
 l Enhancement of SPML operation to get ObjectSid to retrieve the value in the SID 
format along with the base64Binary format.
 l Creation of OneDrive for Azure AD users using OneDrive Provisioning Policy.
 l Configuring secure communication for Active Roles Web interface using Force SSL 
Redirection.

What’s new in Active Roles 7.3

This section provides a summary of the new features included in Active Roles  Version 7.3. 
For detailed information about new features, see the Active Roles 7.3 What’s New Guide.
Major new features in Active Roles Version 7.3:

 l Support for One Identity Hybrid Subscription
 l Support for Hybrid Directory Mailbox Management
 l Support for Microsoft SQL Server 2017 
 l Support for connecting to One Identity Starling, the Software as a Service (SaaS) 
solution of One Identity through Active Roles
 l Integration of Starling Two-factor Authentication with Active Roles through the Web 

Active Roles 7.4 How-To Guide

2
What’s New
 interface
 l Support for customizing Microsoft Office 365 license related operations on User 
provisioning and deprovisioning
 l Enhancements
 l Display the number of members in a Group in the Web interface
 l SPML Extension Enhancement to Modify Shared Mailbox User permissions
 l Back Sync Improvements
 l Sync Service enhancements
 l Password generation policy enhancement
 l Web interface security enhancements
 l Enhanced Web interface accessibility for disabled users

What’s new in Active Roles from

version 7.0
The following features are new in Active Roles as of version 7.0

 l Web Interface has been redesigned for greater clarity and ease of use, to ensure 
consistent look and feel, improve user experience, and simplify and streamline 
management tasks.
 l A new component, Synchronization Service, performs data synchronization and 
replication tasks to enable user, group, or recipient management across various on-
premises systems and in the cloud.
 l Integrated administration of users and mailboxes in Exchange resource forest 
environments, with the ability to create and administer mailboxes by managing 
mailbox users in external forests.
 l Integrated administration of Lync Server users in single and multi-forest 
environments, with the ability to enable, disable or re-enable users for Lync Server 
and administer Lync Server user properties.
 l Various improvements to Active Roles workflow, including new activities to help 
access and modify workflow data context at run time, new activity options, and 
workflow scripting capabilities.
 l Support for Exchange 2010 remote Shell removes the need to install the 
Exchange 2010 Management Tools on the computer running the Active Roles 
Administration Service.
 l Active Roles Configuration for Hybrid Environment.
 l Azure AD /Office 365 Object Management in Hybrid Environment.
 l Microsoft Office 365 License Management.
 l Support for Microsoft Windows Server 2016.

Active Roles 7.4 How-To Guide

3
What’s New
 l Support for Microsoft SQL Server 2016.
 l Support for Microsoft Exchange 2016.
 l Support for Microsoft .Net 4.6.2.
 l Active Roles facilities a new attribute namely 'OperationInitiatorSid' under the 
$Request object, which provide the SID of the initiator who requested the operation. 
This enhances the current Active Roles - Change Auditor integration capability to 
display the correct initiator information.
 l Support for managing Skype for Business through Active Roles.
 l Active Roles in-place upgrade enhancements.
 l Limited support for Exchange Online.
 l Management of Azure AD Contacts.
 l Management of Azure AD Distribution groups.
 l Enhancements to Azure Active Directory and Office 365 functionality:
 l Azure License Reporting.
 l Visual indicator for Azure configuration status.
 l Granular license customization.
 l Support for synchronized identity environments.
 l Azure Application permissions enhancements.
 l Support  for  creating  users,  groups,  and  contacts  in  Azure/Office  365 
through  SPML.

Active Roles 7.4 How-To Guide

4
What’s New
 2

Changes to Setup and Installation

Active Roles 7.4 introduces  the following changes to Setup and Installation:

Unified Setup Wizard

Table 1: Changes to Unified Setup wizard

Version 6.9 and earlier Version 7.3 or later

Numerous MSI files Single ActiveRoles.EXE

The components must be installed in the correct order.  

Silent Install
The Active Roles installer, Setup.exe has command-line options for a silent installation. 
For more details, refer to KB 185799 
Example:
Setup.exe /quiet /install ADDLOCAL=Service,Console /IAcceptActiveRolesLicenseTerms

Configuration Center
The Configuration Center unifies management of core configuration for the Active Roles 
Administration Service and Web Interface, which allows administrators to perform the core 
configuration tasks from a single location.
Highlights include:

 l Initial configuration tasks such as creation of Administration Service instances and 
default Web Interface sites.
 l Import of configuration and management history from earlier Active Roles versions.
 l Management of core Administration Service settings, such as the Active Roles Admin 
account, service account, and database connection.

Active Roles 7.4 How-To Guide

5
Changes to Setup and Installation
 l Creation of Web Interface sites based on site configuration objects of the current 
Active Roles version or site configuration objects imported from  earlier Active 
Roles versions.
 l Management of core Web Interface site settings, such as the site’s address on the 
Web server and configuration object on the Administration Service.
 l Scriptable Configuration Center operations  using Windows PowerShell command-line 
tools provided by the Active Roles Management Shell.

Active Roles 7.4 How-To Guide

6
Changes to Setup and Installation
The following two methods are available for configuring the Active Roles instance:

 l Graphical User Interface  (Active Roles Configuration Center)
 l PowerShell  (Active Roles Management Shell)

Management Shell Integration

The Active Roles Management Shell, which provides Windows PowerShell based command-
line tools (cmdlets) for executing and automating administrative tasks in Active Roles, is a 
part of the Management Tools component included in the Active Roles Setup.
Modules:

 l ActiveRolesManagementShell
 l ActiveRolesConfiguration

ActiveRolesManagementShell

 l Provides cmdlets for managing users, group, computers, and other objects in Active 
Directory via Active Roles; managing digital certificates; and administering certain 
Active Roles objects.
 l Cmdlets are prefixed with QAD or QARS, such as New-QADUser, Add-QADCertificate, or 
New-QARSAccessTemplateLink.

ActiveRolesConfiguration

 l Provides cmdlets for configuring Active Roles Administration Service instances and 
Web Interface sites.
 l Available on 64-bit (x64) systems only. It requires the Active Roles Administration 
Service or Web Interface to be installed; otherwise, the module does not provide 
all cmdlets.
 l The cmdlets provided in this module have their noun prefixed with AR, such as New-
ARDatabase, New-ARService, or New-ARWebSite.

Active Roles 7.4 How-To Guide

7
Changes to Setup and Installation
 3

Changes to System requirements

and Supported platforms

Active Roles 7.4 introduces the following changes to system requirements:

 l Active Roles can no longer be installed on Window Server 2008.
 l Microsoft SQL Server 2005 is no longer supported. Microsoft SQL Server versions 
2008 and later including 2017 are supported. The Configuration Center may be used 
to import Active Roles databases from SQL Server 2005 to a later SQL Server 
version. For details, see “Upgrading the Administration Service” in the Active Roles
Quick Start Guide.
 l To manage Exchange recipients on Exchange Server 2010, Active Roles no longer 
requires the Exchange 2010 Management Tools on the computer running the 
Administration Service.
 l Active Roles supports the following browsers only: Internet Explorer 11, Google 
Chrome, Mozilla Firefox, and Microsoft Edge.
 l Web Interface is optimized for screen resolutions of 1280 x 800 or higher. The 
minimum supported screen resolution is 1024 x 768.
 l Active Roles console requires Internet Explorer 11.

Active Roles 7.3 introduces the following changes to supported platforms:

 l Exchange 2007 and earlier versions are no longer supported.
 l Microsoft Exchange 2013 CU11 is not supported.

Active Roles 7.4 How-To Guide

8
Changes to System requirements and Supported platforms
 4

System Requirements

For the complete  system requirements, please refer to the Active Roles 7.4 Release Notes. 

The following are the important system requirements for Active Roles installation:

 l Operating Systems Supported for Active Roles installation: Microsoft Windows 2008 
R2 and later, including 2019
 l SQL Server requirements: Microsoft SQL 2008 and later, including SQL 2019
 l Microsoft .NET Framework: .NET 4.7.2
 l Other software required for Active Roles may be installed from the Redistributables 
folder on the installation media.

Resource Usage
The sizing of disk space and the SQL database capacities are best planned out by using the 
Resource Usage Calculator, which is found in the Documentation folder on the 
installation disk or image.
The Resource Usage Calculator is included with the installation media and can be 
found under:
Documentation\ ActiveRoles_7.4_ResourceUsageCalc.xls
For more information on the system requirements, please see the Pre-Installation and 
Upgrade section for the Active Roles Diagnostic and System Readiness Checker tools.

Ports Used by Active Roles

If the environment managed by Active Roles is located behind a firewall, then the following 
ports must be open between Active Roles Administration Service and the managed 
environment:

Access to DNS Servers

 l Port 53 TCP/UDP Inbound/Outbound

Active Roles 7.4 How-To Guide

9
System Requirements
Access to domain controllers

 l Port 88 (Kerberos) TCP/UDP Inbound/Outbound
 l Port 135 (RPC endpoint mapper) TCP Inbound/Outbound
 l Port 139 (SMB/CIFS) TCP Inbound/Outbound
 l Port 445 (SMB/CIFS) TCP Inbound/Outbound
 l Port 389 (LDAP) TCP/UDP Outbound
 l Port 636 (LDAP SSL) TCP Outbound
 l Port 3268 (Global Catalog LDAP) TCP Outbound

This port is required if Active Roles is configured to access the domain by using SSL.

 l Port 3269 (Global Catalog LDAP SSL) TCP Outbound

This port is required if Active Roles is configured to access the domain by using SSL.

 l The TCP port allocated by RPC endpoint mapper for communication with the 
domain controller

Active Directory domain controllers can be configured to use specific port numbers for RPC 
communication. For instructions, see http://support.microsoft.com/kb/224196.

Access to Exchange servers

 l Port 135 (RPC endpoint mapper) TCP Inbound/Outbound
 l The TCP port allocated by RPC endpoint mapper for communication with the 
Exchange server

Exchange servers can be configured to use specific port numbers for RPC communication. 
For instructions, see http://support.microsoft.com/kb/270836.

Computer resource management

 l Port 139 (SMB/CIFS on the managed computers) TCP Inbound/Outbound
 l Port 445 (SMB/CIFS on the managed computers) TCP Inbound/Outbound

Computer restart

 l Port 139 (SMB/CIFS on the managed computers) TCP Inbound/Outbound
 l Port 137 (WINS) UDP Outbound
 l Port 138 (NetBIOS datagrams) UDP Outbound

Home folder provisioning and deprovisioning

 l Port 139 (SMB/CIFS on the servers that host home folders) TCP Inbound/Outbound
 l Port 445 (SMB/CIFS on the servers that host home folders) TCP Inbound/Outbound

Active Roles 7.4 How-To Guide

10
System Requirements
Access to SMTP server for e-mail integration

 l Port 25 (Default SMTP port) TCP Outbound

Active Roles uses SMTP port 25 by default. The default port number can be changed in the 
properties of the Mail Configuration object in the Active Roles console. If Mail Configuration 
specifies a different port, open that port rather than port 25.

Access to AD LDS instances

 l The TCP port specified when registering the AD LDS instance with Active Roles

Access to SQL Server

If SQL Server that hosts the Active Roles database is located behind the firewall, open the 
following ports between Active Roles Administration Service and SQL Server:

 l Port 1433 (Default SQL Server instance) TCP Inbound/Outbound

Open this port if the Active Roles database is on the default instance of SQL Server. If a 
different port is assigned to the default instance, open that port rather than port 1433.

 l Port 1434 (SQL Server Browser service) UDP Inbound/Outbound

Open this port if the Active Roles database is on a named instance of SQL Server. In this 
case Active Roles uses UDP port 1434 to determine the port assigned to the named 
instance, open port 1434 along with the TCP port assigned to the named instance.

Access to Active Roles Administration Service

If a firewall is required between Active Roles clients, such as MMC Interface, Web 
Interface, ADSI Provider or Management Shell, and Active Roles Administration Service, 
open the following ports in the firewall:

 l Port 15172 TCP Inbound/Outbound

Access to Web Interface

If the Active Roles Web Interface will be accessed through a firewall, open the 
following ports:

 l Port 80 (Default HTTP) TCP Inbound/Outbound
 l Port 443 (Default HTTPS) TCP Inbound/Outbound

The Web Interface normally runs over port 80, or over port 443 if SSL is enabled (off 
by default).

Synchronization Service

The Synchronization Service requires the following port to be open:

 l Port 15173 TCP Outbound

The Capture Agent requires this port to be open (on the Domain Controller):

Active Roles 7.4 How-To Guide

11
System Requirements
 l Port 7148 TCP Inbound

Active Roles 7.4 How-To Guide

12
System Requirements
 5

Required Permissions and Access

As Active Roles performs operations on objects on behalf of delegated users, the Active 
Roles service account requires adequate permissions. The officially supported 
configuration is to manage Active Directory domains by using a Domain Admin account.
If a Domain Admin's membership is restricted, it is necessary to grant the Active Roles 
service account the following minimum permissions and access:

NOTE: Contact One Identity Sales for any assistance in engaging One Identity Profes-
sional Services.

Access to the Administration Service Computer

The service account must be a member of the local Administrators group on the computer 
running Active Roles Administration service.

Service Publication in Active Directory

For Active Roles clients to discover available Active Role services, the service account 
must be able to publish itself in Active Directory. On the One Identity sub-container, under 
the System container in the domain, grant the following rights:
• Create Container Objects
• Create ServiceConnectionPoint Objects

Access to Managed Domains

The service account must have at least Read Permissions in any Managed Domain. In 
addition, the service account must have Modify Permissions rights on the Active 
Directory objects and containers where the Active Roles security synchronization feature 
will be utilized.

Access to Exchange Organizations

Exchange 2010
To manage Exchange recipients on Exchange Server 2010, the service account or the 
override account must be configured to have sufficient rights in the Exchange organization. 
The rights must be delegated to the service account if an override account is not used; 

Active Roles 7.4 How-To Guide

13
Required Permissions and Access
otherwise, the rights must be delegated to the override account. See the following steps for 
details.

To configure the service account or the override account

 1.  Add the account to the Recipient Management role group. For instructions, see “Add 
Members to a Role Group” at http://technet.microsoft.com/library/dd638143
(EXCHG.141).aspx.
 2.  Add the account to the Account Operators domain security group.
 3.  Enable the account to use remote Exchange Management Shell. For instructions, see 
“Enable Remote Exchange Management Shell for a User” at 
http://technet.microsoft.com/library/dd298084(exchg.141).aspx.
 4.  Ensure that the account can read Exchange configuration data (see Permission to 
read Exchange configuration data).
 5.  Restart the Administration Service after changing the configuration of the account: 
 l Start Active Roles Configuration Center (see “Running Configuration Center” in 
the Active Roles Administrator Guide), go to the Administration Service page in 
the Configuration Center main window, and then click the Restart button at 
the top of the Administration Service page.

NOTE: For instructions for Exchange 2010, 2013, 2016, and 2019, see the relevant 
Microsoft Exchange pages at https://technet.microsoft.com/en-us/library.

The Exchange 2010 management tools are not required on the computer running the 
Administration Service.
Exchange 2013, 2016, or 2019
To manage Exchange recipients on Exchange Server 2013, 2016, or 2019 the service 
account or the override account must be configured to have sufficient rights in the 
Exchange organization. The rights must be delegated to the service account if an override 
account is not used; otherwise, the rights must be delegated to the override account. For 
details, see the steps that follow.

To configure the service account or the override account

 1.  Add the account to the Recipient Management role group. For instructions, see 
“Manage Role Group Members” at http://technet.microsoft.com/library/jj657492
(exchg.150).aspx.
 2.  Add the account to the Account Operators domain security group.
 3.  Enable the account to use remote Exchange Management Shell. For instructions, see 
“Enable remote Shell for a user” in the topic “Manage Exchange Management Shell 
Access” at http://technet.microsoft.com/library/dd638078(exchg.150).aspx.
 4.  Ensure that the account can read Exchange configuration data (see Permission to 
read Exchange configuration data).
 5.  Restart the Administration Service after changing the configuration of the account: 
Start Active Roles Configuration Center (see “Running Configuration Center” in the 
Active Roles Administrator Guide), go to the Administration Service page in the 

Active Roles 7.4 How-To Guide

14
Required Permissions and Access
 Configuration Center main window, and then click the Restart button at the top of the 
Administration Service page.

Permission to read Exchange configuration data

To perform Exchange recipient management tasks, Active Roles requires Read access to 
Exchange configuration data in Active Directory. This requirement is met if the service 
account (or the override account, if specified) has administrator rights. For example the 
service account , is a member of the Domain Admins or Organization Management group. 
Otherwise, provide the account Read permission in the Microsoft Exchange container, using 
the ADSI Edit console.

NOTE: The following instructions apply to the ADSI Edit console that ships with 
Windows Server 2012 or Windows Server 2012 R2.

To provide Read access to the service account using the ADSI Edit console:

 1.  Open the ADSI Edit console, and connect to the Configuration naming context.
 2.  In the ADSI Edit console, navigate to the Configuration/Services container, right-
click Microsoft Exchange in that container, and then click Properties.
 3.  On the Security tab in the Properties dialog box that appears, click Advanced.
 4.  On the Permissions tab in the Advanced Security Settings dialog box, click Add.
 5.  On the Permission Entry page, configure the permission entry:
 a.  Click Select a principal, and select the desired account.
 b.  Ensure that the Type box indicates Allow.
 c.  Ensure that the Applies onto box indicates: This object and all
descendant objects.
 d.  In the Permissions area, select the List contents and Read all properties
check boxes.
 e.  Click OK.
 6.  Click OK to close the Advanced Security Settings dialog box, and then click OK to 
close the Properties dialog box.

Support for Exchange Remote Shell

When performing Exchange recipient management tasks on Exchange Server 2010 or later, 
Active Roles uses remote Exchange Management Shell to communicate with Exchange 
Server. Hence, it is not required to install the Exchange management tools on the computer 
running the Administration Service.

To use remote Exchange Management Shell, the Administration Service must be

running on a computer that has:

 l Windows  Server  2008  R2  SP1  or  a  later  version  of  the  Windows  Server 
operating  system.

Active Roles 7.4 How-To Guide

15
Required Permissions and Access
  l Microsoft .NET Framework 4.5 installed (see “Installing the .NET Framework 4.5, 
4.5.1” at https://msdn.microsoft.com/library/5a4x27ek%28VS.110%29.aspx).
 l Windows Management Framework 3.0 installed (see “Windows Management 
Framework 3.0” at https://www.microsoft.com/en-
us/download/details.aspx?id=34595).

Remote Shell also requires the following:

 l TCP port 80 must be open between the computer running the Administration Service 
and the remote Exchange server.
 l The user account the Administration Service uses to connect to the remote Exchange 
server (the service account or the override account) must be enabled for remote 
Shell. To enable a user account for remote Shell, update that user account by using 
the Set-User cmdlet with the RemotePowerShellEnabled parameter set to $True.
 l Windows  PowerShell  script  execution  must  be  enabled  on  the  computer  running 
the  Administration  Service.  To  enable  script  execution  for  signed  scripts,  run 
the  Set-ExecutionPolicy  RemoteSigned  command  in  an  elevated  Windows 
PowerShell  window.

Active Roles 7.4 How-To Guide

16
Required Permissions and Access
 6

Product Licensing

After installing Active Roles 7.x (or upgrade to Active Roles 7.x), no additional steps are 
required to activate the purchased commercial license for Active Roles.
Product usage statistics may be used to verify Active Roles licensing compliance. For 
further details, see Evaluating Product Usage in the Active Roles Administrator Guide.

Active Roles 7.4 How-To Guide

17
Product Licensing
 7

Pre-Installation and Upgrade

Active Roles 7.4 supports a direct upgrade from versions 6.9  and later  including 7.2.1.

NOTE: If customizations have been implemented by One Identity Professional 
Services, please contact One Identity Sales before proceeding with an installation or 
upgrade, as all customizations may not function with newer versions.

Installing Active Roles Diagnostic Tools

To install Active Roles Diagnostic Tools

 1.  Install the Active Roles Diagnostic Tools, which consists of Active Roles System 
Checker, which should be run in order to confirm that the server has adequate 
resources to host and run Active Roles 7.4. Navigate to the installation media.
 2.  Go to Solutions | Diagnostic Tools.
 3.  Double-click to run ActiveRolesDiagnosticsTools_1.4.0.msi. 
The Active Roles Diagnostic Tools Setup Wizard is displayed. 
 4.  Click Next.
 5.  In the License Terms window, read and accept the license agreement and click Next.
 6.  In the Custom Setup window, select the appropriate tools to install. It is 
recommended to install the Active Roles Log Viewer, Directory Changes Monitor, and 
the Active Roles System Checker for later use. Click Next.
 7.  In the Ready to Install window, click Install.
 8.  After the tools are installed, click Finish.

Active Roles 7.4 How-To Guide

18
Pre-Installation and Upgrade
Checking System Readiness
To check the system readiness

 1.  From the Windows Applications, Start Menu, select Active Roles System Checker.

The Active Roles System Checker window is displayed. 

 2.  Select Computer | System Readiness Checks.

 3.  In the Confirm System Readiness Checks window, select the appropriate components 
to check for and click Check.
 4.  In the System Readiness Checks window, review the summary and confirm that the 
computer has passed the required checks. Take appropriate action before installing 
Active Roles. For example, if there is a warning about insufficient Memory (RAM), 
then upgrade the Memory to the recommended amount.
 5.  In the Active Roles System Checker, select SQL Server Checks under 
Environment. Enter the SQL Server name and appropriate credentials for the Active 
Roles service account and click Check.
 6.  Review the summary to confirm that the SQL Server passed the checks.
 7.  In the Active Roles System Checker, select Active Directory Checks under 
Environment. Enter the Domain Controller name and appropriate credentials for the 
Active Roles service account and click Check.
 8.  Review the summary to confirm the account has adequate permissions in Active 
Directory. 
In this example, the checker found Exchange in the environment. Active Roles 
service account is not a member of the Exchange groups and therefore must be 
added appropriately in order to administer Exchange-related tasks in Active Roles.
A progress window is displayed. After completion, the summary is displayed.

 9.  On this screen, click the Additional Resources link to learn more about Active 

Roles. Click Finish.

Active Roles 7.4 How-To Guide

19
Pre-Installation and Upgrade
 8

Clean Installation

For an installation demonstration, please refer to the following knowledge base article:
https://support.oneidentity.com/kb/258459

Installing the Active Roles service

To install the Active Roles service

 1.  Run ActiveRoles.exe.
 2.  Accept the licensing agreement and click Next.
 3.  Select the desired components and click Next.
 4.  Review the summary and click Install.
By default, the I want to perform configuration option is selected. 

 5.  Click Finish to launch the Configuration Center.

 6.  Under the Administration Service option, click Configure.
 7.  Select a service account that will run the Active Roles service and click Next.
 8.  Choose the appropriate security group that will hold the role of the Active Roles 
Admin group and click Next.
 9.  If this is the first installation of Active Roles 7.4, select New Active Roles database 
and click Next.
 10.  Enter the appropriate SQL server, database name and credentials. Click Next.
 11.  After completing, click Finish.

Active Roles 7.4 How-To Guide

20
Clean Installation
Installing the Web interface
To install the Active Roles Web interface

 1.  Launch the Active Roles Configuration Center.
 2.  Click Dashboard.
 3.  Click Configure under the Web Interface section.
 4.  Select the appropriate service to connect to and click Configure.
 5.  After completing, click Finish.

Active Roles 7.4 How-To Guide

21
Clean Installation
 9

Upgrade from Active Roles 6.9

Upgrading from Active Roles 6.9  to 7.x version is a side-by-side upgrade, which does not 
interrupt operations or affect the configuration of the currently installed Active Roles 
version. To ensure smooth upgrade to the new Active Roles version, upgrade the 
Administration Service first, and then upgrade the Web Interface.
Active Roles 6.9 components are not used in the upgrade and neither are any components 
from the earlier version uninstalled.
Before upgrading to the latest version of Active Roles, the add-ons of the earlier versions 
must be uninstalled.

Impact on Office 365 Add-On

 l After an upgrade of Active Roles components to Active Roles 7.4, the Office 365 add-
on which was supported in the earlier versions of Active Roles, ceases to work. 
Hence, it is recommended to uninstall the Office 365 add-on prior to the upgrade of 
Active Roles.
 l Office 365 add-on is not supported on Active Roles 7.3 or later and must be 
uninstalled prior to the installation of Active Roles 7.1.
 l Active Roles 7.4 manages Office 365 and Azure AD natively.

For an upgrade demonstration, please refer to the following knowledge base article:
https://support.oneidentity.com/kb/257995

Prerequisites for Active Roles 6.9

upgrade
Before any upgrade is performed, first consider the following:

 l There is no need to break replication when upgrading to Active Roles 7.4 from 6.9 as 
Active Roles 7.3 or later does not support an in-place upgrade in this scenario.  A 

Active Roles 7.4 How-To Guide

22
Upgrade from Active Roles 6.9
 side-by-side installation of Active Roles must be performed and replication must be 
configured post installation on the new instance of Active Roles.

NOTE: During and post-installation of Active Roles 7.4, the existing installation 
of Active Roles 6.9 will be available and fully functional. Hence, users will not 
be affected during the upgrade process with the exception of Dynamic Groups. 
For more details please review the knowledge base article, https://sup-
port.oneidentity.com/kb/211388.

 l An upgrade of the Active Roles components may affect custom solutions. Custom 
solutions (such as scripts and other modifications), which work fine as expected with 
an earlier version of Active Roles may cease to work after the upgrade. Before 
starting an upgrade, test the existing solutions with the new version of Active Roles 
in a lab environment to verify that the solutions continue to work as expected after 
the upgrade.
 l If ERFM (Exchange Resource Forest Management) is installed on the Active Roles 6.9 
version, it must be uninstalled before installing 7.4 as ERFM is now part of the 
product. Failure to uninstall ERFM beforehand may result in conflicts and issues.
 l If Lync Add-On is installed, it must be uninstalled before installing Active Roles 7.4 as 
Lync is now an integrated product feature.
 l If Office 365 Add-On is installed, it must be uninstalled before installing Active Roles 
7.4 as this functionality is replaced with the inbuilt Azure Active Directory Hybrid 
Integration.
 l For additional information, please review Solution 111679:
https://support.oneidentity.com/kb/111679

 l Due to the design changes implemented in Active Roles 7.x in the Web Interface, any 
Web Interfaces and customizations from Active Roles 6.9 may not function in Active 
Roles 7.4. It is recommended not to import. Please refer to KB 189186 for additional 
information:
https://support.oneidentity.com/kb/189186

To perform the Upgrade

 1.  From the installation media, run ActiveRoles.exe.
 2.  Accept the licensing agreement and click Next.
 3.  Select the desired components and click Next.
 4.  Review the summary and click Install.
 5.  By default, the I want to perform configuration option is selected. Click Finish
to launch the Configuration Center
 6.  In  the  Configuration  Center,  under  the  Administration  Service  option  click 
Configure.
 7.  Select a service account that will run the Active Roles service and click Next.
 8.  Choose the appropriate security group that will hold the role of the Active Roles 
Admin group and click Next.

Active Roles 7.4 How-To Guide

23
Upgrade from Active Roles 6.9
  9.  If this is the first installation of Active Roles 7.4, select New Active Roles database 
and click Next.
 10.  Enter the appropriate SQL server, database name and credentials. Click Next.
 11.  After completing, click Finish.
 12.  In the Configuration Center, under Dashboard click Import Configuration, specify 
the Source SQL server, database and access credentials, and then click Next.
 13.  Click Next.
 14.  If  the  current  Active  Roles  7.4  service  is  running,  stop  it  and  then  click  Next
to  continue.
 15.  If you have the encryption key, provide it. If not, select Do not import encrypted
data and click Next.
 16.  If you do not have the encryption key, you must re-enter the credentials  for any 
Managed Domains, which are not managed by the Active Roles Service account.
The Add-On Advisor checks if there are any incompatible Add-Ons installed the 
Wizard will not proceed. Before continuing, uninstall the Add-Ons from the Active 
Roles 6.9 server.

 17.  Click Next.
 18.  Once ready, click Import.

Importing Change History

The Change History from Active Roles 6.9 database is not imported during the initial 
import, as the Change History may be extremely large and thus would take a long time 
for the initial Setup to complete. Active Roles provides a separate utility for importing 
Change History. 

 1.  In the Active Roles Configuration Center, click Import Management History under 

Administration Service.
 2.  Enter  the  Active  Roles  6.9  source  database  and  appropriate  credentials  and 
click  Next.
 3.  Select the destination database and click Next.
 4.  Choose the records to import and click Next.
 5.  Confirm the settings and click Import.
The progress screen is displayed, and after completion, the summary is displayed.

Active Roles 7.4 How-To Guide

24
Upgrade from Active Roles 6.9
 10

In-Place Upgrade from Active Roles

7.x

Office 365 Add-On that was previously available for Active Roles is no longer compatible 
with Active Roles 7.4. Before proceeding with the upgrade from 7.0.x to 7.4, the Office 365 
Add-On must be uninstalled.
For an upgrade demonstration, please refer to the following knowledge base articles:

 l https://support.oneidentity.com/kb/257996
 l https://support.oneidentity.com/kb/257997

Backing up the Active Roles Database

Before upgrading, it is recommended to back up the Active Roles database. For general 
best practices, please refer to the following Microsoft article:
https://docs.microsoft.com/en-us/sql/relational-databases/backup-restore/create-a-full-
database-backup-sql-server

Prerequisites for in-place upgrade from Active Roles 7.x

It is recommended to back up the current Web Interfaces if any customizations have been 
implemented.
Any Web Interfaces that were created in Active Roles 7.2.x will continue to function in 7.4. 
However, it is recommended to thoroughly test before upgrading, as some customizations 
may not work as expected in newer versions of Active Roles.

To back up the Web Interface Configurations

 1.  Launch the Active Roles Configuration Center.
 2.  Click Web Interface.
 3.  Select the desired site(s) and click Export Configuration.

To upgrade Active Roles

 1.  Run ActiveRoles.exe from the installation media.
 2.  Click Next to continue.

Active Roles 7.4 How-To Guide

25
In-Place Upgrade from Active Roles 7.x
  3.  Accept the license agreement and click Next.
 4.  Review the summary and warning. If the Office 365 Add-On is installed in the 7.0.x 
instance, uninstall it before continuing.
 5.  If the system does not restart, click Update Service Instance in the 
Configuration Center.
 6.  If the system restarts and the Configuration Center does launch automatically, 
launch the Configuration Center and click Update Service Instance.
Due to the update of the database schema, the 7.0 versions of the Websites are no 
longer compatible. 

 7.  Click Manage Sites under Web Interface in the Configuration Center.

 8.  Make note of the current websites and configurations used (For example, 
ARWebAdmin, using configuration “Site for Administrators”).
 9.  Delete all the sites and click +Create.
 10.  Enter the Alias of the site, for example ARWebAdmin and click Next.
 11.  On the Configuration screen, ensure Create from a template is selected.
 12.  Enter a Configuration name, select the original Template to import from (for 
example, “Site for Administrators 7.0”), and then click Create.
 13.  Click Finish.

Active Roles 7.4 How-To Guide

26
In-Place Upgrade from Active Roles 7.x
 11

Synchronization Service

Formerly a standalone product called Quick Connect, the Synchronization Service is now 
part of Active Roles 7.4.
With Synchronization Service, complete automation can be implemented to process data 
synchronization between the data systems.
Synchronization Service increases the data management efficiency by allowing automation 
of the creation, deprovision, and update operations between data systems. For example, 
when an employee joins or leaves the organization, the related information in the data 
systems managed by Synchronization Service is automatically updated, thereby reducing 
the administrative workload and getting the new users up and running faster.
In order to synchronize identity data between external data systems, Synchronization 
Service must be configured to connect to these data systems through connectors. A 
connector enables Synchronization Service to access specific data system to read and 
synchronize data in that system according its settings. Out of the box, Synchronization 
Service includes a number of built-in connectors:

 l Active Roles versions 7.4, 7.3, 7.2.x, 7.1, 7.0 and 6.9
 l Identity Manager version 8.1, 8.0, or 7.0
 l Quest One Identity Manager version 6.1 or 6.0
 l Delimited text files
 l Microsoft Active Directory Domain Services
 l Microsoft Active Directory Lightweight Directory Services
 l Microsoft Azure Active Directory
 l Microsoft Exchange Server
 l Microsoft Skype for Business Server
 l Microsoft Office 365
 l Microsoft SharePoint
 l Microsoft SQL Server
 l OLE DB-compliant relational database
 l Generic LDAP Directory service
 l MY SQL Database

Active Roles 7.4 How-To Guide

27
Synchronization Service
  l OpenLDAP Directory service
 l Salesforce
 l ServiceNow
 l IBM DB2 Database
 l RACF Connector

Figure 1: Technical Overview

Active Roles 7.4 How-To Guide

28
Synchronization Service
 12

Capture Agent
Synchronization Service Capture Agent allows password synchronization between Active 
Directory domains managed by Synchronization Service and other connected data 
systems. The following diagram shows how the Password Synchronization feature of 
Synchronization Service works:

Figure 2: Password Synchronization

Capture Agent tracks changes to user passwords in the source Active Directory domain and 
provides that information to Synchronization Service, which in turn synchronizes the 
changes with target connected data systems by using the configured password 
synchronization rules. To synchronize passwords, install a Capture Agent on each domain 
controller in the Active Directory source domain.

Upgrade from Quick Connect

If Quick Connect is configured with synchronization workflows that contain similar 
connector in Synchronization Service, then those synchronization workflows can be 
transferred to Synchronization Service.
The following synchronization workflows can be transferred from the following Quick 
Connect versions:

Active Roles 7.4 How-To Guide 29

  l Quick Connect Sync Engine 5.2.0, 5.3.0, 5.4.x, or 5.5
 l Quick Connect Express for Active Directory 5.3.0, 5.4.0, 5.4.1, or 5.5.0
 l Quick Connect for Cloud Services 3.3.0, 3.4.0, or 3.5.0
 l Quick Connect for Base Systems 2.2.0 or 2.3.0

Limitations
Synchronization Service is unable to run synchronization workflows that employ 
connections to the following systems:

 l ActiveRoles Server 6.5
 l Google Apps
 l Novell eDirectory
 l ODBC-compliant data source
 l OpenDS directory service
 l Oracle Database
 l Oracle User Accounts
 l PeopleSoft HCM
 l Red Hat Directory Server
 l SAP Systems
 l Sun One Directory Server
 l Workday

If it is necessary to synchronize data held in these systems, continue using Quick Connect 
as not all connectors provided by Quick Connect are included with Synchronization Service. 
Alternatively, One Identity Manager may support these systems.

Synchronization Service upgrade

For an upgrade demonstration, please refer to the following knowledge base article:
https://support.oneidentity.com/kb/226332

To upgrade Synchronization Service

 1.  Install Synchronization Service on the computer running Quick Connect or on a 
different host.
 2.  Configure Synchronization Service to use a new database for storing configuration 
settings and synchronization data. To perform this step, use the Configuration Wizard 

Active Roles 7.4 How-To Guide 30

 that appears when the Synchronization Service Administration Console starts for the 
first time after installation.
 3.  Import configuration settings from Quick Connect to Synchronization Service. 

NOTE: Before proceeding with this step, it is highly recommended to disable 
the scheduled workflows and mapping operations in Quick Connect. The 
scheduled workflows and mapping operations may be started after this step is 
completed.

To import configuration settings:
 a.  On the computer where the Synchronization Service is installed, start the 
Synchronization Service Administration Console.
 b.  In the upper right corner of the Administration Console window, click the gear 
icon, and then click Import Configuration.
 c.  In the wizard that appears, select the correct version of Quick Connect Sync 
Engine from which to import the configuration settings. Optionally, the Import
sync history check box may be selected to import the sync history along with 
the configuration settings.
 d.  Follow the steps in the wizard to complete the import operation. If the 
synchronization data to be imported is stored separately from the configuration 
settings, then, on the Specify source SQL Server databases step, select 
the Import sync data from the specified database check box, and specify 
the database.
 2.  Retype access passwords in the connections that were imported from Quick Connect. 
This is required due to security reasons. The import of configuration settings does not 
retrieve the encrypted passwords from Quick Connect. Use the Synchronization 
Service Administration Console to make changes to each connection as appropriate, 
depending upon the data system to which the connection applies.

 3.  If the synchronization workflows involve synchronization of passwords, install the 
new version of Capture Agent on the domain controllers. 
The new version of Capture Agent replaces the old version. However, as the new 
version supports both Synchronization Service and Quick Connect, the password 
synchronization functions of Quick Connect will not be lost after the Capture 
Agent is updated.

Communication Ports
Table 2: Communication ports

Port Protocol Type of traffic Direction of

traffic

53 TCP/UDP DNS Inbound, 

Active Roles 7.4 How-To Guide 31

Port Protocol Type of traffic Direction of
traffic

Outbound

88 TCP/UDP Kerberos Inbound, 

Outbound

135 TCP RPC Endpoint mapper Inbound, 

Outbound

139 TCP SMB/CIFS Inbound, 

Outbound

445 TCP SMB/CIFS Inbound, 

Outbound

389 TCP/UDP LDAP Outbound

3268 TCP LDAP Outbound

3269 TCP SSL (only required if SSL is used to connect to AD) Outbound

636 TCP SSL Outbound

15173 TCP Synchronization Service Inbound, 

Outbound

7148 TCP Capture Agent (only if Synchronization Service is used  Inbound, 

to sync passwords to AD) Outbound

For  further  information  regarding  Synchronization  Service,  refer  to  the  Active Roles
7.4 Synchronization Service Administrator Guide included  with  the  Active  Roles 
installation  media.

Active Roles 7.4 How-To Guide 32

 13

Starling Two-Factor Authentication

Active Roles version 7.4 supports integration with One Identity Starling services. The 
Starling Join feature in Active Roles now enables you to connect to One Identity Starling, 
the Software as a Service (SaaS) solution of One Identity. The Starling Join feature enables 
access to the Starling services through Active Roles thus allowing to benefit from the 
Starling services such as Two-factor Authentication and Identity Analytics and Risk 
Intelligence.
To start the wizard, click Configure in the One Identity Starling area on the Dashboard page 
in the Configuration Center main window. For further information and step-by-step 
instructions, see the “Initial configuration” topic in the “Installing and configuring the Web 
Interface” section in the Active Roles Quick Start Guide.
A video demonstration is available in the following knowledge base article:
https://support.oneidentity.com/kb/258341
In  order  to  use  Starling  Two-Factor  Authentication  with  Active  Roles,  you  must  first 
join  One  Identity  Starling  to  Active  Roles  on  the  Active  Roles  Configuration  Center.  The 
Join  to  One  Identity  Starling  wizard  also  includes  links,  which  provide  assistance  for 
using  Starling:

 l The Online link displays information about the Starling product and the benefits you 
can take advantage of by subscribing to Starling services.
 l The Trouble Joining link displays the Starling support page with information on the 
requirements and process for joining with Starling.

Active Roles 7.4 How-To Guide

33
Starling Two-Factor Authentication
 14

Reports

Reporting is an optional component of Active Roles. To use Active Roles reports, the 
following components are required:

 l Microsoft SQL Server Reporting Services (SSRS) must be installed and configured.

NOTE: If the SQL Server service and SRSS are on different hosts, a “Double-
Hop” authentication issue may occur. For more information, see the knowledge 
base article, https://support.oneidentity.com/kb/69693.

 l The Active Roles service account must have sufficient permissions to create and 
write to a database on the SQL Server.

NOTE: The database cannot be pre-created, and must be created by  Active 
Roles.

 l The Active Roles service account must have sufficient permission to publish reports 
on the SRS server.

NOTE: Quest Knowledge Portal is no longer included with Active Roles 7.x. To 
view reports, use the native SQL Server Report URL.

How to configure Reports

Please refer to Video Solution 156240, which demonstrates how to configure Reports in 
Active Roles:
https://support.oneidentity.com/kb/156240

Can Reports databases be re-used?

The Active Roles 7.x database structure is different than previous versions and therefore 
old Report databases, such as from Active Roles version 6.9, cannot be used directly.

Active Roles 7.4 How-To Guide

34
Reports
However, the new Active Roles Collector and Report Pack wizard provides the ability to 
import events from an earlier database. Simply select Import events from an earlier 
database version and follow the prompts to import the older Collector database data.

Active Roles 7.4 How-To Guide

35
Reports
 15

Customizations

Custom solutions (scripts or other modifications) may not function properly after an 
upgrade due to compatibility issues. Prior to attempting an upgrade, test existing 
customizations with the new version of Active Roles in a lab or test environment to verify 
that the customizations function as expected. If compatibility issues arise during the test 
process, please contact One Identity Sales to arrange assistance from One Identity 
Professional Services.

Active Roles 7.4 How-To Guide

36
Customizations
 16

Troubleshooting

The following sections provide information on troubleshooting Active Roles:

 l Performance
 l Safe Mode

Performance
For Active Roles performance, please refer to the following knowledge base article:
https://support.oneidentity.com/kb/185471

Safe Mode
Active Roles provides a troubleshooting option, referred to as safe mode, which starts the 
Administration Service in a limited state.  When safe mode is enabled, the Administration 
Service disregards the following:

 l Custom policies
 l Workflows
 l Scripts
 l Scheduled tasks
 l Other customizations that may block Active Roles from starting and operating 
normally, and rejects connections from any user other than an Active Roles Admin.

Active Roles Admin can connect to the Administration Service and make changes in order 
to fix or remove customizations that cause issues, and then disable safe mode.

Active Roles 7.4 How-To Guide

37
Troubleshooting
How to use Safe Mode

 1.  Log on to the computer running the Administration Service with a user account that 
has administrator rights on that computer.

NOTE: Local administrator rights are required to enable or disable safe mode.

 2.  Open  Active  Roles  Management  Shell  on  the  computer  running  the 
Administration  Service.
 3.  Click Active Roles 7.4 Management Shell on the Apps page or Start menu 
depending upon the version of the Windows operating system.
 4.  To enable safe mode, enter the following commands at the Management Shell 
command prompt:
l Set-ARService -SafeModeEnabled $true
l Restart-ARService
 5.  To disable safe mode, enter the following commands at the Management Shell 
command prompt:
l Set-ARService -SafeModeEnabled $false
l Restart-ARService

Error and Log resources

Active Roles writes most events to its own Event log in Windows Event Viewer, under 
Applications and Services, called Active Roles Admin Service.
This event log can be used to help determine root causes for issues and typically 
provide more detailed error information if any issues are encountered within the console 
or Web Interface.
In addition to the Event log, there is a debug option for the Active Roles Administration 
service that is disabled by default. Enabling logging can be accessed either in the Active 
Roles MMC Console or via the Active Roles Configuration Center.
In addition to the Synchronization Center, the ADSI provider and MMC (console), it is 
recommended to use the Active Roles Configuration Center as it provides options to enable 
logging for the Web Interface component. The Log Viewer can then be launched directly 
from here for any of these logs.

Active Roles 7.4 How-To Guide

38
Troubleshooting
Figure 3: Active Roles Console

Figure 4: Active Roles Configuration Center

In versions earlier to Active Roles 7.0, after the logs are generated, the logs are sent to 
One Identity Support for analysis as the logs on their own can be difficult to read.

Active Roles 7.4 How-To Guide

39
Troubleshooting
With Active Roles 7.0 we have provided a new tool called the Active Roles Log Viewer, 
which breaks down the log to a simple and readable format so that customers can review 
the logs on their own before engaging One Identity Support.

Active Roles Log Viewer

The Log Viewer tool provides the ability to browse and analyze diagnostic log files created 
by the Active Roles Administration Service, as well as event log files created by saving the 
Active Roles event log in Event Viewer on the computer running the Administration Service. 
Log Viewer helps to study the sequence or hierarchy of requests processed by the 
Administration Service, identify error conditions that the Administration Service 
encountered during request processing, and find Knowledge Articles that apply to a given 
error condition.
With Log Viewer, both Active Roles diagnostic log files (ds.log) or saved event log files 
(.evtx) can be opened, and  the following can be viewed:

 l Errors encountered by the Administration Service and recorded in the log file
 l Requests processed by the Administration Service and traced in the log file
 l All trace records found in the diagnostic log file
 l All events found in the event log file

Select an error in the list, and choose a command to look for the solution in Knowledge 
Base. The command performs a search in One Identity Software Knowledge Base to list the 
Knowledge Articles that can provide helpful information on how to troubleshoot the 
selected error. Log Viewer can be used to:

 l Search the list for a particular text string, such as an error message
 l Filter the list by various conditions, to narrow the set of list items of interest
 l View detailed information about each list item, such as error details, request details 
or stack trace

Log file size

The logs grow in size quickly. Therefore, it is recommended to enable logging right before 
and disable logging immediately after the issue has been reproduced.
The file captures any activity being performed by the service, including the tasks 
performed by connected users while debug logging is enabled.
In some scenarios, it may be required to leave the logging on for a specific period of time. 
Due to the logs getting stored on the computer running Active Roles, sufficient hard drive 
space may not be  available. In this event, the following solution can help to set logging for 
a specific interval and move the logs to another drive or network share:

 l How to automate Active Roles logging (debug):

https://support.oneidentity.com/kb/8617
For the Web Interface, there is a separate log file,<name of Site>.log.

Active Roles 7.4 How-To Guide

40
Troubleshooting
The default Location of the Web Interface log is here:
C:\Program Files\One Identity\Active Roles\7.4\Web\Public\Log
As with the ds.log file, the Web Interface log can grow quickly as well. It is recommended 
to turn it on while reproducing an issue only.

Active Roles 7.4 How-To Guide

41
Troubleshooting
 17

Replication

For a video demonstration, please refer to the following knowledge base article:
https://support.oneidentity.com/kb/234198
For additional information and troubleshooting, please refer to the Active Roles 7.4
Administration Guide.

Active Roles 7.4 How-To Guide

42
Replication
 18

Understanding Management History

The Management History feature provides information on who did what and when it was 
done with regard to the Active Directory management tasks performed using Active Roles.
This feature provides a clear log, documenting the changes that have been made to a given 
object, such as a user or group object. The log includes entries regarding actions 
performed, success or failure of the actions, as well as which attributes were changed.
The Management History feature can be used to examine:

 l Change History Information on changes that were made to directory data via 
Active Roles.
 l User  Activity  Information  on  management  actions  that  were  performed  by  a 
given  user.

Both Change History and User Activity use the same source of information—the 
Management History log, also referred to as the Change Tracking log. For information on 
the configuration settings of the Change Tracking log, see the Management History 
configuration section.
Active Roles also includes reports to examine management history by collecting and 
analysing event log records. For more information on reports, see the Active Roles 
Reporting section. However, the process of retrieving and consolidating records from the 
event log may be time-consuming and inefficient.

NOTE: You must import the Management History from the old version after an 
upgrade in order to perform Deprovisioning operations and Undo Temporal Group 
operations.

Considerations and best practices

The Management History feature (also known as Change History or Change
Tracking) is designed to help investigate promptly what changes were recently made to 
directory data, as well as when it was done and by whom. However, this feature does not 
provide for data change auditing exploring large volumes of data changes that occurred 
during a long period of time. For this reason, in addition to the Management History 
feature, Active Roles provides a suite of reports for change tracking and auditing, which is 

Active Roles 7.4 How-To Guide

43
Understanding Management History
part of the Active Roles Report Pack. Each of these options, Management History and 
Report Pack, has its own advantages and limitations. Follow the recommendations in this 
section to choose the one that is best suited.
The Management History feature can be used to examine changes that were made to 
directory data via Active Roles. The feature is designed to help answer the following 
typical questions:

 l Who made the most recent changes to a given user or group object?
 l Who modified a given user or group object during the last X days?
 l What  changes  were  made  to  a  given  user  object  last  night  (yesterday,  the 
day  before)?
 l Have  any  planned  modifications  of  a  given  user  or  group  object  actually  been 
performed?
 l What objects did a given delegated administrator modify during the last X days?

Management History can be accessed instantly whenever an investigation is required or 
troubleshoot a problem that results from inappropriate modifications of directory data. 
Management History includes a dedicated repository to store information about data 
changes, referred to as the Change Tracking log, and GUI to retrieve and display 
information from that repository. No additional tasks, such as collecting or consolidating 
information, are required to build Management History results. However, the advantages 
of the Management History feature also entail some limitations. Before using the 
Management History feature, consider the following recommended best practices and 
limitations of using this feature. The main factor to consider is the size of the Change 
Tracking log. To ensure real-time update of the log on all Administration Services, the log 
is normally stored in the Active Roles configuration database, but can be separated into its 
own database if required. This imposes some limitations on the log size. By default, the 
Change Tracking log is configured to store information about changes that occurred within 
last 30 days. If the setting is increased, do so carefully; otherwise, the following problems 
may be encountered:

 l Excessive increase in the log size significantly increases the time required to build 
and display Change History and User Activity results.
 l As the log size grows, so does the size of the configuration database. This 
considerably increases the time required to back up and restore the database, and 
causes high network traffic replicating the database when an additional 
Administration Service is joined to Active Roles replication.
 l The GUI is not suitable to represent large volumes of Management History results in 
a manageable fashion. Since there is no filtering or paging capabilities, it may be 
difficult to sort through the results.

To address these limitations, Active Roles provides different means for change auditing, 
change-tracking reports, included with the Active Roles Report Pack. These reports are 
designed to answer the following questions:

 l What management tasks were performed on a given object within a certain 
period of time?

Active Roles 7.4 How-To Guide

44
Understanding Management History
  l What management tasks were performed on a given object during the object’s 
entire life time?
 l When was a certain attribute of a given object modified?

Change-tracking reports are based on data collected from event logs. A separate log is 
stored on each computer running the Administration Service, and each log contains events 
generated by one Administration Service only. Therefore, to use reports, the events from 
all event logs need to be consolidated to form a complete audit trail. The process of 
consolidating events, referred to as the data collection process, is performed by a separate 
Active Roles component—Collector. The Collector wizard can be configured to execute data 
collection jobs, and schedule them to run on a regular basis. The main limitation of change-
tracking reports is the fact that the information needs to be collected and consolidated in a 
separate database before the reports can be built. The data collection process exhibits the 
following disadvantages:

 l Collecting data may be a very lengthy operation and the database size may grow 
unacceptable when collecting all events that occurred within a long period of time in 
a large environment.
 l Collecting data is impossible over slow WAN links. This limitation is inherent to the 
Active Roles component intended to collect data for reporting.

Management History configuration

The configuration of Management History includes the following elements:

 l Change-tracking Policy Builds the data pertinent to history of changes made to 
directory objects, and specifies what changes are to be included in the reports on 
change history and user activity.
 l Change Tracking Log Configuration Specifies how many change requests are to be 
stored in the log.
 l Replication  of  Management  History  Data  Specifies  whether  to  synchronize 
Management  History  data  between  Administration  Services  that  use  different 
databases.

Reference
Management History is being synchronized, the Active Roles service is unavailable:
https://support.oneidentity.com/kb/103363
Management History Wizard:
https://support.oneidentity.com/kb/90375

Important Considerations

The Management History Migration Wizard was designed for a "one-to-one" database 
migration for an Active Roles upgrade. It was designed to speed up the upgrade process as 

Active Roles 7.4 How-To Guide

45
Understanding Management History
the history migration can be quite lengthy - sometimes in excess of 25 hours (depending on 
history and environment).
The tool has never been tested in migrating several Management History databases to one. 
This type of scenario is not supported.
However, the tool can be re-run several times from the same source database in this 
upgrade scenario. The import for the Management History database is a Merge import and 
adds any changes to the target Active Roles database.

NOTE: The Configuration database import functionality performs a Replace action. 
This operation overwrites current settings.
Active Roles stores its configuration data in the Configuration database in SQL. It is 
recommended to backup Configuration and Management History databases prior to 
the upgrade.
For more information on upgrade paths, refer to the knowledge base article 
https://support.oneidentity.com/kb/111679.

Active Roles 7.4 How-To Guide

46
Understanding Management History
 19

Service Account

Active Roles 7.0 introduced the Configuration Center, which provides a simple method for 
changing or updating the Active Roles service account.

Changing Active Roles service account

credentials
To change the Active Roles Administration Service account

 1.  Launch the Active Roles Configuration Center.
 2.  Click Administration Service tab.
 3.  Click Change on the Service Account.
 4.  Enter the new credentials and click Change.
 5.  After completing, click Finish.

To start using the new credentials, you must restart the service. Restart the service 
immediately or later, at a more convenient time.

Changing Service account credentials

for SQL database connection
To change the account that is used to run the Active Roles Administration
Service

 1.  Launch the Active Roles Configuration Center.

 2.  Click the Administration Service tab.
 3.  On the Active Roles database section, click Change .
 4.  Enter the new credentials and click Next.

Active Roles 7.4 How-To Guide

47
Service Account
  5.  Click Change to commit the changes.
 6.  Click Finish.

To start using the new credentials, you must restart the service. Restart the service 
immediately or later, at a more convenient time.

Active Roles 7.4 How-To Guide

48
Service Account
 About us

About us

One Identity solutions eliminate the complexities and time-consuming processes often 
required to govern identities, manage privileged accounts and control access. Our solutions 
enhance business agility while addressing your IAM challenges with on-premises, cloud and 
hybrid environments.

Contacting us
For sales or other inquiries, visit https://www.oneidentity.com/company/contact-us.aspx 
or call +1-800-306-9329.

Technical support resources

Technical support is available to One Identity customers with a valid maintenance contract 
and customers who have trial versions. You can access the Support Portal at 
https://support.oneidentity.com/.
The Support Portal provides self-help tools you can use to solve problems quickly and 
independently, 24 hours a day, 365 days a year. The Support Portal enables you to:

 l Submit and manage a Service Request
 l View Knowledge Base articles
 l Sign up for product notifications
 l Download software and technical documentation
 l View how-to-videos at www.YouTube.com/OneIdentity
 l Engage in community discussions
 l Chat with support engineers online
 l View services to assist you with your product

Active Roles 7.4 How-To Guide

49
About us