When deploying the Administration Service, you might need to import configuration data from an existing database to ensure that the new Administration Service instance has the same configuration as the existing one. Importing configuration data to a newly created database instead of attaching the Administration Service to an existing database is necessary if the version of the Administration Service you are deploying is greater than the version of the database you want to use. Some examples of such a situation are the following:
-
Upgrading the Administration Service while preserving its configuration.
-
Restoring configuration data from a backup copy of the database whose version does not match the version of the Administration Service.
IMPORTANT: During in-place upgrade, when importing from the source database (Configuration and Management History database), the following database permissions are automatically migrated from the previously used (source) SQL database to the new (destination) SQL database:
The service account that is used for performing the in-place upgrade or the import or migration operation should have the following permissions in the SQL Server to perform the operation:
If the SQL access account used for performing the in-place upgrade does not have permission to create a database, then you must manually create the database for Active Roles. In the Configuration Center, during the initial configuration, select Use a pre-created blank database. For more information, see Knowledge Base Article 4303098 on the One Identity Support Portal.
By default, Copy database users, permissions, logins, and roles is selected, but you can clear it in the following locations depending on the operation:
-
During in-place upgrade: in the Upgrade configuration window.
-
Importing configuration: Import Configuration > Source Database > Configure advanced database properties.
-
Importing management history: Import Management History > Source database > Configure advanced database properties.
If you want to create a new database for the imported configuration data during the configuration of the Administration Service instance, perform the following procedure. After the initial configuration of the Administration Service instance, you can use the Active Roles Configuration Center to import the configuration data to the newly-created database.
To import configuration data to a new database
-
From the Windows Start menu, open the Active RolesConfiguration Center.
-
To open the Import configuration wizard, navigate to Administration Service <, Import configuration.
-
On the Source database page, specify the database from which you want to import the configuration data, and click Next.
-
Select the required Database type.
-
In Database Server name, enter the database instance that hosts the source database in the format <Computer>\<Instance> (for named instances) or <Computer> (for default instances). In these formats, <Computer> stands for the FQDN of the computer running SQL Server or the name of the Azure SQL database server.
-
In Database name, enter the name of the source database.
-
Under Connect using, select the appropriate authentication option.
-
If your Windows logon account has sufficient rights to write data to the destination database, click Windows authentication.
-
If you have a SQL Server login with sufficient rights, click SQL Server authentication and enter the login name and password.
-
If you have an Azure AD login with sufficient rights, click Azure Active Directory authentication and enter the login name and password.
-
The Destination database page identifies the database of the Administration Service instance to which you will import data. Under Connect using, select the appropriate authentication option, and click Next.
-
If your Windows logon account has sufficient rights to write data to the destination database, click Windows authentication.
-
If you have a SQL Server login with sufficient rights, click SQL Server authentication and enter the login name and password.
-
If you have an Azure AD login with sufficient rights, click Azure Active Directory authentication and enter the login name and password.
-
The Add-on advisor page lists the add-ons installed for the previous version of Active Roles. Uninstall the add-ons and click Next.
NOTE: Before you continue importing the configuration data, uninstall the add-ons manually from the earlier version using the Active Roles Add-on Manager, and also uninstall them from the system, if applicable.
-
On the Import of Encrypted Data page, select one of the following options:
-
If you do not have a backup of the secret key for the source database, click Do not import encrypted data.
In this case, the encrypted data from the source database (such as the override account password for managed domain registrations) will not be available in the destination database. Because of this, you will need to re-enter the override account password later in the managed domain registrations with the Administration Service instance that uses the destination database.
For more information, see Backing up the encryption key in the Active Roles Installation Guide.
-
The Reauthenticate Tenants page lists the configured Azure tenants in the source database. To reauthenticate a tenant, click Reauthenticate next to its name.
|
|
CAUTION: You must reauthenticate the tenant(s). Otherwise, Active Roles does not receive the required permissions to manage existing tenants, and tenant administration will not work correctly. |
NOTE: After a successful upgrade, in the Configuration Center, under Azure AD Configuration, you must consent the Azure tenants manually.
-
In the Services association page, configure the Administration Service instances for running the following:
-
Dynamic groups
-
Group families
-
Scheduled tasks
-
Select This server or Other. Selecting Other allows you to specify another Administration Service instance in a fully qualified domain name (FQDN) format. If the value is empty, the current Administration Service is used.
NOTE: Services association does not update certain scheduled tasks. For example, scheduled tasks that cannot be edited (Managed Object Counter) or scheduled tasks that are set to All servers.
-
Select Run Services association immediately or Schedule Services association.
NOTE: If Services association is scheduled to a specific time, but the upgrade or import operation is still in progress or completes after the scheduled Services association time, then the services will not be associated. In such cases, you must associate the Services manually by running the template workflow Update Services To Execute On available in the built-in workflow container.
To ensure dynamic groups, group families, and scheduled tasks continue to function after an import, the installation configures the new Active Roles server as the initiating server for the listed tasks. This configuration runs after an upgrade.
NOTE: Alternatively, you can perform Services association any time using the template workflow Update Services To Execute On available in the built-in workflow container. You can configure the parameters in the script that the workflow uses to the required Administration Service instances, such as, Dynamic Group Service, Group Family Service, Scheduled Task Service. You can select the Administration Service instance to use from the drop-down list. The drop-down list displays all the currently running Administration Service instances connected to the current configuration database. If the parameter value is not selected, then the current Administration Service instance will be used.
-
In the Summary page, review your settings, then click Next.
-
Follow the instructions in the wizard to complete 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.
NOTE: Depending on the infrastructure, the import operation may take several minutes to complete.
After you imported the configuration of your earlier Active Roles version, import the Management History data from the database used by your Administration Service of the earlier version. To import Management History data, you must identify that database.
To identify the database
-
Open the Active Roles Console and connect to the older-version instance of the Administration Service (see Connecting to the Administration Service in the Active Roles Administration Guide).
-
Select the Console tree root, and on the page in the details pane, expand the Management History Databases and Replication area.
Identify the database name, SQL Server, database type name from the first string in the Management History Databases and Replication area that has the following format: Database <name> on SQL Server <name> Database Type <type>. You can also find this information in the Administration Service pane of the Configuration Center.
After identifying the database, import Management History using the Import Management History wizard of the Configuration Center. For more information, see Importing data to the new Management History database in the Active Roles Administration Guide.
After configuring the Administration Service, the Management History data storage will be empty with the option to create a new database. During the import of configuration data, the Configuration Center transfers only the administrative right assignments, policy definitions, administrative view settings, workflow definitions and other parameters that determine the Active Roles work environment. Management History data is excluded from the import operation to reduce the time it takes to upgrade the configuration of the Administration Service.
The Management History data describes changes that were made to directory data via Active Roles. This includes information about directory data management tasks, such as:
-
The changes a user performed.
-
The users performing the changes.
-
The time the change was performed.
The Management History data is used for change history and user activity reports. In addition, the Management History data storage holds information about various tasks related to approval workflows and temporal group memberships.
After configuring the Administration Service and importing configuration data from an existing database, you must take additional steps to transfer the Management History data. You can do this using the Import Management History wizard in the Active Roles Configuration Center.
You can populate the newly-created Management History database with your existing Management History data. This ensures that the data is available in the Active Roles user interfaces after configuring the Administration Service to use the new Management History database. You can import existing Management History data with the Active Roles Configuration Center on the computer running the Administration Service instance.
IMPORTANT: The reports created by the Change History or User Activity commands (available both in the Active Roles Web Interface and the Active Roles Console components) only include information about the changes that were made using a specific Administration Service group. This group must share a common database from the connected Management History database. If the change history data is not imported from the previously available database, the data will not be included in the new database.
To import Management History data
-
From the Windows Start menu, open the Active RolesConfiguration Center.
-
In the Configuration Center main window, under Administration Service, click Manage Settings.
-
To open the Import Management History wizard, on the Administration Service page, click Import Management History.
-
On the Source database page, select the source database:
-
Database Type: Select the required database type from the drop-down:
-
On-premises
-
Azure SQL database
-
Database Server name: Enter the name of the database instance that hosts the source database.
-
Database name: Enter the name of the source database.
-
Under Connect using , select the authentication option:
-
If your Windows login account has sufficient rights to write data to the destination database, click Windows authentication.
-
If you have an SQL Server login with sufficient rights, click SQL Server authentication and enter the login name and password.
-
If you selected Azure SQL as the database type and you have an Azure AD login with sufficient rights, click Azure Active Directory authentication and enter the login name and password.
-
(Optional) Copy SQL Server users and login data after importing Management History data. This option is enabled by default, if you selected the On-premises database type.
NOTE: Due to limitations in Azure SQL, Active Roles cannot synchronize SQL Server logins to Azure SQL databases.
To synchronize SQL Server users to Azure SQL, One Identity recommends using system-provided Microsoft tools, such as Azure Data Studio or Azure Database Migration Service (DMS) Classic.
For more information on migrating Microsoft SQL Server users to Azure SQL, see the following Microsoft documentation resources:
To skip the synchronization of users and login data:
-
Click Configure advanced database properties.
-
Clear the Copy database users, permissions, logins and roles check box.
-
Click Apply.
-
Click Next.
On the Destination database page, specify the database of the Administration Service instance to which you are importing data, and select the authentication option.
-
Under Connect using, select the authentication option:
-
If your Windows login account has sufficient rights to write data to the destination database, click Windows authentication.
-
If you have an SQL Server login with sufficient rights, click SQL Server authentication and enter the login name and password.
-
If you selected Azure SQL as the database type and you have an Azure AD login with sufficient rights, click Azure Active Directory authentication and enter the login name and password.
-
Click Next.
On the Records to import page, to import all data records, select All records. To import only data records from a specific time interval, select Records in the following date range, then specify a date range.
NOTE: Consider the following when selecting whether to import all data records or only records from a specific date range:
-
If you select to import all data records, or specify a date range which also includes the current day, then the Management History wizard will create a timestamp for the current day to ensure that all data records created up to the point of starting the migration will be imported. This means that the wizard will import all data that existed in the source database at the time the migration started, but will not import any data records that have been created after starting the migration.
-
If you select a date range manually, you cannot select future dates.
-
Data for unfinished temporal group memberships are imported only if you import Management History data for a selected date range.
-
Click Next.
On the Ready to import page, review your settings. If needed, return to the previous pages and make adjustments.
-
To start the import process once your changes are finalized, click Import.
On the Run page, you can see the progress of the import process. After the operation finished, the wizard shows a summary and a link that you can use to check the import log.
NOTE: During the import process, consider the following:
-
You can cancel the import process at any time. However, the wizard will not stop the import immediately, but only after it finishes the currently performed step of the operation. Active Roles will not delete the data that the wizard has successfully imported to the destination database before canceling the operation.
-
If an SQL exception occurs during migration, the operation will not be canceled. Instead, the wizard will restart the migration of that specific batch of data. The retry policy ensures that, unless there is a persistent network or database error, you do not need to restart the import process manually.
If the SQL exception is network-related or transient, the wizard will retry the migration of the failed batch up to 3 times. If the SQL exception occurs for other reasons, the wizard will only retry the migration once.
Depending on the severity of the exception, one of the following events can occur:
-
If the error is resolved and the migration of the failed batch is successful, then the wizard proceeds with importing the remaining data.
-
If the error is not resolved after the maximum number of retries, the wizard cannot proceed with the migration and cancels the process. You can restart the migration manually, but if the issue persists, check the log for details and contact your network administrator or database administrator.
-
To check the detailed log of the import operation, click View log. To exit the wizard, click Finish.
NOTE: The Import Management History wizard only adds new data, keeping intact any data that already exists in the destination database. You can import your legacy Management History data at any time after you have configured the Administration Service, without the risk of losing any data.
If multiple instances of the Administration Service use a single database, then you can perform the upgrade as follows.
To upgrade multiple Administration Service instances with a shared database
-
Upgrade one of the Administration Service instances as described in Configuring the initial Administration Service in the Active Roles Installation Guide.
-
Now that you have the database of the new version, upgrade the remaining instances of the Administration Service one by one.
-
In the Configure Administration Service wizard, on the Configuration Database Options page, select Existing Active Roles database.
-
On the Connection to Database page, specify the database created during the upgrade of the first Administration Service instance. You do not need to import configuration as the database already has that data imported.
-
On the Management History Database Options page, select Existing Active Roles database.
-
On the Connection to Database page, specify the database created during upgrade of the first Administration Service instance. You do not need to import the management history as the database already has that data imported.
