Active Roles 7.2 - Feature Guide

Management Shell integrated into Active Roles

Management Shell integrated into Active Roles

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

• The ActiveRolesManagementShell module 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. The cmdlets provided by this module have their noun perfixed with QAD or QARS, such as New-QADUser, Add-QADCertificate, or New-QARSAccessTemplateLink.
• The ActiveRolesConfiguration module provides cmdlets for configuring Active Roles Administration Service instances and Web Interface sites. This module is 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. The cmdlets provided by this module have their noun prefixed with AR, such as New-ARDatabase, New-ARService, or New-ARWebSite.

You can use the Import-Module command to load these modules and gain access to all cmdlets provided by Active Roles Management Shell.

How to start

1. Log on to the computer on which the Administration Service or Web Interface is installed.
2. Open Active Roles Management Shell on that computer. To open Management Shell, click Active Roles 7.2 Management Shell on the Apps page or Start menu depending upon the version of your Windows operating system.
3. Enter the QuickRef command at the Management Shell command prompt to view the Reference Manual that provides detailed information about all commands available in Active Roles Management Shell.

Administering Active Roles

Administering Active Roles

This section summarizes the features and enhancements that improve the user experience of those who deploy and administer Active Roles, implementing and maintaining the Active Roles-based administrative structure.

Brand-new installation and upgrade experiences

With the brand-new installation and upgrade experiences, Active Roles has become much easier to evaluate, deploy, upgrade and configure. Key highlights include:

• Unified Setup wizard  Active Roles Setup now provides a single wizard for installing all components, including the Administration Service, Web Interface and Console (MMC Interface). You no longer need to install components using individual installer packages.
• Configuration Center  Active Roles now includes Configuration Center—a solution for configuring Administration Service instances and Web Interface sites that allows you to perform the core configuration tasks from a single location. For further details, see Configuration Center later in this document.
• Side-by-side deployment  You can deploy the new Active Roles version side-by-side with your earlier Active Roles version on the same computers, and perform an upgrade without interrupting operations or affecting the configuration of your earlier Active Roles version.

Separation of installation and configuration

Active Roles now provides a single installation file SETUP.EXE instead of numerous installation MSI files. With this single installation file, you can install the core Active Roles components, including Administrative Service, Web Interface and Management Shell.

Some solutions still have separate MSI files, such as Add-on Manager or SPML Provider. You can get them from the Active Roles distribution media.

Side-by-side installation

Active Roles can now coexist with an earlier version of Active Roles on the same computer, so you can run the new version of Active Roles side-by-side with the earlier Active Roles version. In this way, you can use the same hardware during upgrade of Active Roles from an earlier version while keeping the earlier version available for business needs.

Note that the name of the Windows service running the Administrative Service and the names of the default Web Interface sites have changed, to avoid conflicts with the names used in the earlier Active Roles version.

Configuration Center

Active Roles 7.2 introduces a new configuration management solution that unifies management of core configuration for the Active Roles Administration Service and Web Interface. Configuration Center provides a single solution for configuring Administration Service instances and Web Interface sites, allowing administrators to perform the core configuration tasks from a single location. Highlights include:

• Initial configuration tasks such as creation of Administration Service instances and default Web Interface sites
• Import of configuration and management history from earlier Active Roles versions
• Management of core Administration Service settings such as the Active Roles Admin account, service account, and database connection
• Creation of Web Interface sites based on site configuration objects of the current Active Roles version or by importing site configuration objects of earlier Active Roles versions
• Management of core Web Interface site settings such as the site’s address on the Web server and configuration object on the Administration Service

The Configuration Center operations are fully scriptable using Windows PowerShell command-line tools provided by the Active Roles Management Shell.

Benefits of using Configuration Center

While managing core configuration of Active Roles components is not new, Configuration Center unifies the functionality of multiple earlier tools in a single, simple, wizard-based user interface. Configuration Center provides a single point of access to management wizards for all configuration tasks.

With earlier Active Roles versions, administrators were required to use several tools for core configuration tasks: the Setup program to perform initial configuration, and to import configuration data during upgrade; the Management History Migration tool to import management history data; and the Web Interface Sites Configuration tool to create and manage Web Interface sites on the Web server. Configuration Center integrates the functionality exposed in those tools into a single, unified console, and adds a number of new capabilities, making Active Roles much easier to deploy and upgrade.

Configuration Center is composed of the following elements:

• Initial configuration wizards  After completing Active Roles Setup, the administrator uses the initial configuration wizards to create a new Active Roles instance, including the Administration Service and Web Interface. The wizards allow the administrator to specify, in a logical manner, the configuration settings that were previously exposed in the Setup program.

In earlier Active Roles versions, Administration Service Setup prompted for various configuration settings, and created a new, fully configured Administration Service instance; Web Interface Setup created the default Web Interface sites, which required the Administration Service to be up and running. Overall, this setup practice complicated and slowed Active Roles setup, as the completion of Active Roles installation would be delayed until the administrator responded to the prompts and the Setup program finished all the core configuration tasks. Configuration Center allows the administrator to postpone these tasks, and perform them at a convenient time after completing Active Roles Setup. By separating the configuration tasks from the Setup program, Configuration Center simplifies Active Roles installation and streamlines deployment of Active Roles components in an enterprise.

• Hub pages and management wizards  Once initial configuration has been completed, Configuration Center provides a consolidated view of the core Active Roles configuration settings, and offers tools for changing those settings. Hub pages in the Configuration Center main window display the current settings specific to the Administration Service and Web Interface, and include commands to start management wizards for changing those settings.
  • From the Administration Service page, the administrator can view or change the service account, admin account, and database; import configuration data or management history data from an Active Roles database of an earlier version or the current version; view status information, such as whether the Administration Service is started and ready for use; start, stop or restart the Administration Service.

  Earlier Active Roles versions allowed you to import configuration data only one time, when using the Setup program for in-place upgrade of the Administration Service. In many cases, this limitation complicated the process of deploying a new Active Roles version that would inherit the configuration of an existing, earlier Active Roles version. By allowing configuration data to be imported at any convenient time, Configuration Center makes Active Roles much easier to upgrade. You can now install the new Administration Service version side-by-side with an earlier version and then import configuration data to the new version as needed.

  • From the Web Interface page, the administrator can view, create, modify or delete Web Interface sites; export configuration of any existing Web Interface site to a file; open each site in a Web browser. The site parameters available for setting, viewing and changing include the site’s address (URL, which is based on the Web site and alias of the Web application that implements the Web Interface site on the Web server) and the configuration object that stores the site’s configuration data on the Administration Service. When creating or modifying a Web Interface site, the administrator can reuse an existing configuration object, or create a new configuration object based on a template or by importing data from another configuration object or from an export file.

Earlier Active Roles versions exposed this functionality in a separate tool for configuring Web Interface sites on the Web server. Configuration Center replaces that tool, to make configuration management more efficient by providing a unified experience for administrators to perform various types of configuration tasks.

Wizards that start from hub pages help the administrator manage configuration settings. Management wizards streamline the core configuration tasks by reducing time it took in earlier versions to change the service account, admin account and database; import configuration and management history; and configure Web Interface sites on the Web server.

• Configuration Shell  A new Windows PowerShell module in Active Roles Management Shell enables access to all Configuration Center features and functions from a command line or from a script, allowing for unattended configuration of Active Roles components. The ActiveRolesConfiguration module provides command-line tools (cmdlets) for the key set of configuration tasks, such as creation of the Active Roles database, creation or modification of Administration Service instances and Web Interface sites, data exchange between Active Roles databases and between site configuration objects, querying the current state of the Administration Service, and starting, stopping or restarting the Administration Service. The cmdlets provided by the ActiveRolesConfiguration module have their noun prefixed with AR, such as New-ARDatabase, Set-ARService, or Set-ARWebSite.

Configuring a local or remote Active Roles instance

Configuration Center is installed as part of the Management Tools component when you install Active Roles on a 64-bit (x64) system. You can use this tool to perform configuration tasks on the local or remote computer that has the current version of the Administration Service or Web Interface installed. Configuration Center looks for these components on the local computer and, if no components has been found, prompts you to connect to a remote computer. Another way to connect to a remote computer is by using the menu on the heading bar at the top of the Configuration Center main window.

When connecting to a remote computer, Configuration Center prompts you for a user name and password. This must be the name and password of a domain user account that belongs to the Administrators group on the remote computer. In addition, whether you are going to perform configuration tasks on the local computer or on a remote computer, your logon account must be a member of the Administrators group on the computer running Configuration Center.

To perform configuration tasks on a remote computer, Configuration Center requires Windows PowerShell remoting to be enabled on that computer. Run the Enable-PSRemoting command in the PowerShell console to enable remoting (see the Enable-PSRemoting help topic at http://go.microsoft.com/fwlink/?LinkID=144300 for further details). On Windows Server 2012 or later, remoting is enabled by default.

Running Configuration Center

Configuration Center is installed and, by default, automatically started after you install the Administration Service or Web Interface, allowing you to perform initial configuration tasks on the computer on which you have installed those components. If you close Configuration Manager and want to start it again, you can start Configuration Manager from the following locations:

• On Windows Server 2008 R2, select Start | All Programs | Active Roles7.2 | Active Roles 7.2 Configuration Center.
• On Windows Server 2012 or later, click the Active Roles 7.2 Configuration Center tile on the Apps page.

As Configuration Center can manage Active Roles not only on the local computer but also on remote computers, it is possible to use it on a client operating system as well as on server operating systems. You can install Configuration Center by installing Active Roles Management Tools on a 64-bit (x64) server or client operating system, and then connect it to a remote computer on which the Administration Service or Web Interface is installed. To start Configuration Center on a client operating system:

• On Windows 7, select Start | All Programs | Active Roles 7.2 Active Roles | Active Roles 7.2 Configuration Center.
• On Windows 8 or later, click the Active Roles 7.2 Configuration Center tile on the Apps page.

To run Configuration Center on a given computer, you must be logged on with a user account that has administrator rights on that computer.

If neither the Administration Service nor the Web Interface is installed on the local computer, then Configuration Center prompts you to select a remote computer. In the Select Server dialog box that appears, supply the fully qualified domain name of a server, on which the Administration Service or the Web Interface (or both) is installed, and type the logon name and password of a domain user account that has administrator rights on that server. You can connect to a remote server at any time by selecting the Connect to another server command from the menu on the heading bar at the top of the Configuration Center main window, which also displays the Select Server dialog box.

Tasks you can perform in Configuration Center

Configuration Center enables you to perform:

• Initial configuration tasks, creating the Administration Service instance and the default Web Interface sites
• Configuration management tasks, letting you manage the existing instance of the Administration Service or Web Interface

Initial configuration tasks

Unlike Setup programs of earlier Active Roles versions, the current Setup program only installs and registers the Active Roles files, without performing any configuration. Upon completion of Active Roles Setup, Configuration Center is used to create an instance of the Administration Service and deploy the default Web Interface sites. Here you can find an overview of these initial configuration tasks.

Configure the Administration Service

The Configure Administration Service wizard creates the Administration Service instance, getting the Administration Service ready for use. The wizard prompts you to supply the following settings:

• The logon name and password of the account in which this Administration Service instance will be running (service account)
• The name of the group or user account that will have full access to all Active Roles features and functions through this Administration Service instance (Active Roles Admin)
• The database in which this Administration Service instance will store the configuration data and management history data

You have the option to create a new database, or use an existing database of the current Active Roles version. It is possible to have multiple Administration Service instances use the same database.

• The authentication mode that this Administration Service instance will use when connecting to the database

With the Windows authentication option, the Administration Service will use the credentials of the service account; with the SQL Server authentication option, the Administration Service will use the SQL login name and password you supply in the wizard.

To start the wizard, click Configure in the Administration Service area on the Dashboard page in the Configuration Center main window.

Configure the Web Interface

The Configure Web Interface wizard creates the default Web Interface sites, getting the Web Interface ready for use. The wizard prompts you to choose which Administration Service will be used by the Web Interface you are configuring. The following options are available:

• Use the Administration Service instance running on the same computer as the Web Interface
• Use the Administration Service instance running on a different computer

This option requires you to supply the fully qualified domain name of the computer running the desired instance of the Administration Service.

• Let the Web Interface choose any Administration Service instance that has the same configuration as the given one

This option requires you to supply the fully qualified domain name of the computer running the Administration Service instance of the desired configuration. If your environment employs Active Roles replication, this must be the computer running the Administration Service instance whose database server acts as the Publisher for the Active Roles configuration database.

To start the wizard, click Configure in the Web Interface area on the Dashboard page in the Configuration Center main window.

Administration Service management tasks

After installing Active Roles, you perform the initial configuration task to create the Administration Service instance, getting it ready for use. Then, you can use Configuration Center to:

• View or change the core Administration Service settings such as the service account, the admin account, and the database
• Import configuration data from an Active Roles database of the current version or an earlier version to the current database of the Administration Service
• Import management history data from an Active Roles database of the current version or an earlier version to the current database of the Administration Service
• View the state of the Administration Service
• Start, stop or restart the Administration Service

View the core Administration Service settings

On the Administration Service page in the Configuration Center main window, you can view:

• The logon name of the service account
• The name of the group or user account that has the Active Roles Admin rights
• The SQL Server instance that hosts the Active Roles database and the name of the Active Roles database
• The database connection authentication mode (Windows authentication or SQL Server login)

Change the core Administration Service settings

From the Administration Service page in the Configuration Center main window, you can change:

• The service account—Click Change in the Service account area. In the wizard that appears, supply the logon name and password of the domain user account in which you want the Administration Service to run.
• The Active Roles Admin account—Click Change in the Active Roles Admin area. In the wizard that appears, specify the group or user account you want to have the Active Roles Admin rights.
• The Active Roles database—Click Change in the Active Roles database area. In the wizard that appears, specify the SQL Server instance and the database you want the Administration Service to use, and choose the database connection authentication mode (Windows authentication or SQL Server login). You have the option to specify a separate database for storing management history data.

Import configuration data

The task of importing configuration data arises when you upgrade the Administration Service. In this case, you need to transfer the Active Roles configuration data from the database used by your Administration Service of the earlier version to the database used by your Administration Service of the new version. To perform this task, click Import Configuration on the Administration Service page in the Configuration Center main window, and follow the steps in the Import Configuration wizard that appears.

The Import Configuration wizard prompts you to specify the Active Roles database from which you want to import the configuration data (source database) and identifies the database of the current Administration Service to which the configuration data will be imported (destination database), letting you choose the connection authentication mode (Windows authentication or SQL Server login) for each database. Then, the wizard performs the import operation. During the import operation, the wizard retrieves and upgrades the data from the source database, and replaces the data in the destination database with the upgraded data from the source database.

Import management history data

Although this task looks similar to the task of importing configuration data, there are important differences:

• Due to a much larger volume of management history data compared to configuration data, importing management history data takes much longer than importing configuration data.
• As management history data has dependencies on configuration data (but not vice versa), configuration data must be imported first, and then management history data can be imported as needed.

Because of these considerations, Configuration Center provides a different wizard for importing management history. The distinctive features of the Import Management History wizard are as follows:

• The wizard does not replace the existing data in the destination database. It only retrieves and upgrades management history records from the source database, and then adds the upgraded records to the destination database.
• The wizard allows you to specify the date range for the management history records you want to import, so you can import only records that occurred within a particular time frame instead of importing all records at a time.
• Canceling the wizard while the import operation is in progress does not cause you to lose the import results, so you can stop the import operation at any time. The records imported by the time that you cancel the wizard are retained in the destination database. If you start the wizard again, the wizard imports only records that were not imported earlier.

To start the Management History Import wizard, click Import Management History on the Administration Service page in the Configuration Center main window. The wizard prompts you to specify the Active Roles database from which you want to import the management history data (source database) and identifies the database of the current Administration Service to which the management history data will be imported (destination database), letting you choose the connection authentication mode (Windows authentication or SQL Server login) for each database. Then, the wizard lets you choose whether you want to import all management history records or only records within a certain date range, and performs the import operation. During the import operation, the wizard retrieves and upgrades management history records from the source database, and adds the upgraded records to the destination database.

View the state of the Administration Service

On the Administration Service page in the Configuration Center main window, you can view the state of the Administration Service, such as:

• Ready for use  Administration Service is running and ready to process client requests
• Getting ready  Administration Service has just started and is preparing to process client requests
• Stopping  Administration Service is preparing to stop
• Stopped  Administration Service is stopped
• Unknown  Unable to retrieve the state information

Start, stop or restart the Administration Service

You can start, stop or restart the Administration Service by clicking the Start, Stop or Restart button at the top of the Administration Service page in the Configuration Center main window. If the function of a given button is not applicable to the current state of the Administration Service, the button is unavailable.

Web Interface management tasks

After installing Active Roles, you perform the initial configuration task to create the default Web Interface sites, getting the Web Interface ready for use. Then, you can use Configuration Center to:

• Identify the Web Interface sites that are currently deployed on the Web server running the Web Interface
• Create, modify or delete Web Interface sites
• Export a Web Interface site’s configuration object to a file

Here you can find an overview of these tasks.

Identify Web Interface sites

The Web Interface page in the Configuration Center main window lists all Web Interface sites that are deployed on the Web server running the Web Interface. For each Web Interface site, the list provides the following information:

• IIS Web site  The name of the Web site that holds the Web application implementing the Web Interface site
• Web app alias  The alias of the Web application that implements the Web Interface site, which defines the virtual path of that application on the Web server
• Configuration  Identifies the object that holds the Web Interface site’s configuration and customization data on the Active Roles Administration Service

From the Web Interface page, you can open Web Interface sites in your Web browser: Click an entry in the list of Web Interface sites and then click Open in Browser on toolbar.

Create a Web Interface site

You can create a Web Interface site by clicking Create on the Web Interface page in the Configuration Center main window. The Create Web Interface Site wizard appears, prompting you to:

• Choose the Web site to contain the Web application that implements the new Web Interface site
• Supply the desired alias for that Web application. The alias defines the virtual path that becomes part of the Web Interface site’s address (URL).

Then, the wizard lets you specify the object to hold the configuration and customization data of the new Web Interface site on the Active Roles Administration Service. You can choose from the following options:

• Create the object from a template

  The new site will have the default configuration and customization based on the template you select.

• Use an existing object

  The new site will have the same configuration and customization as any existing Web Interface site that also uses the object you select. This option is intended for the scenario where you create an additional instance of one of your existing Web Interface sites on a different Web server.

• Create the object by importing data from another object

  The new site will inherit the configuration and customization of the site that used the object you select for data import. This option is mainly intended for the upgrade scenario where you create Web Interface sites of the new Active Roles version that have the same configuration and customization as your Web Interface sites of an earlier Active Roles version. In this scenario, you import the configuration data of the earlier version to the Administration Service of the new version (which also imports the site configuration objects of the earlier version), and then create configuration objects for Web Interface sites of the new version by importing data from site configuration objects of the earlier version.

• Create the object by importing data from an export file

Active Roles

Modify a Web Interface site

From the Web Interface page in the Configuration Center main window, you can make changes to existing Web Interface sites: Click an entry in the list of sites and then click Modify on the toolbar. The Modify Web Interface Site wizard starts, allowing you to:

• Choose the Web site to contain the Web application that implements the Web Interface site
• Supply the desired alias for that Web application. The alias defines the virtual path that becomes part of the Web Interface site’s address (URL).

Then, the wizard lets you specify the object to hold the site’s configuration and customization data on the Active Roles Administration Service. You can choose from the following options:

• Keep on using the current object (default option)

The site’s configuration will remain intact. The wizard displays the name and version of the current configuration object.

• Create the object from a template

The site will have the default configuration and customization based on the template you select.

• Use an existing object

The site will have the same configuration and customization as any existing Web Interface site that also uses the object you select. You could use this option to deploy an additional instance of one of your existing Web Interface sites on a different Web server.

• Create the object by importing data from another object

  The site will inherit the configuration and customization of the site that used the object you select for data import. You could use this option to deploy a Web Interface site of the new Active Roles version with the same configuration and customization as one of your Web Interface sites of an earlier Active Roles version. In this case, you import the configuration data of the earlier version to the Administration Service of the current version (which also imports the site configuration objects of the earlier version), and then create the site configuration object by importing data from the appropriate site configuration object of the earlier version.

• Create the object by importing data from an export file

  The site will inherit the configuration and customization of the site whose configuration data was saved to the export file you specify. You can choose an export file of any supported Active Roles version.

Delete a Web Interface site

On the Web Interface page in the Configuration Center main window, you can delete Web Interface sites: Click an entry in the list of sites and then click Delete on the toolbar. This operation only deletes the Web Interface site from the Web server, without deleting the site’s configuration object from the Administration Service.

When you delete a site, the site’s configuration object remains intact on the Administration Service. You can set up a Web Interface site with the same configuration as the site you have deleted, by choosing the option to use that object on the Configuration step in the wizard for creating or modifying Web Interface sites.

Export a Web Interface site’s configuration object to a file

From the Web Interface page in the Configuration Center main window, you can export site configuration objects: Click an entry in the list of sites and then click Export Configuration on the toolbar. A wizard starts, prompting you to specify the export file. The wizard then retrieves the site’s configuration object from the Administration Service, and saves the data from that object to the export file.

The export file could be considered a backup of the site’s configuration. You can set up a Web Interface site with the configuration restored from an export file, by importing that file on the Configuration step in the wizard for creating or modifying Web Interface sites.

Logging management tasks

You can use Configuration Center to enable or disable, and view diagnostic logs for the Active Roles components that are installed on the computer running Configuration Center. On the Logging page, Configuration Center lists the following information:

• Component  Name of the component, such as Administration Service, Web Interface or Console (MMC Interface)
• Logging  Indicates whether logging is enabled or disabled for the given component, and the logging level, such as Basic or Verbose
• Log location  Depending upon the component, identifies either the folder containing the log files or the log file for that component

The toolbar on the Logging page allows you to perform the following tasks:

• To enable or disable logging for a given component, select the component in the list, and then click Modify on the toolbar.
• To open the folder that contains the log file or files for a given component, select the component in the list, and then click Browse with Explorer on the toolbar.
• To examine the Administration Service log file in Log Viewer, select Administration Service in the list of components and then click Open in Log Viewer on the toolbar. For information about Log Viewer, see Active Roles Log Viewer later in this document.

How to start

Configuration Center is installed and, by default, automatically started after you install the Administration Service or Web Interface, allowing you to perform initial configuration tasks on the computer on which you have installed those components. If you close Configuration Center and want to start it again, you can start Configuration Center from the following locations:

• On Windows Server 2008 R2, select Start | All Programs | Active Roles Active Roles 7.2 | Active Roles 7.2 Configuration Center.
• On Windows Server 2012 or later, click the Active Roles 7.2 Configuration Center tile on the Apps page.