Tips for finding Knowledge Articles

  • - Enter just a few key words related to your question or problem
  • - Add Key words to refine your search as necessary
  • - Do not use punctuation
  • - Search is not case sensitive
  • - Avoid non-descriptive filler words like "how", "the", "what", etc.
  • - If you do not find what you are looking for the first time,reduce the number of key words you enter and try searching again.
  • - Minimum supported Internet Explorer version is IE9
Home  >

KB-6906: How to convert a distribution group to a security group

App Access Service ,   App Gateway Service ,  

11 July,17 at 06:59 PM

This article describes a product change with Centrify Identity Service starting with version 16.5.

What is changing?

Centrify will be deprecating support for Local Security Groups (LSGs) and Distribution Lists (DLs) to manage security using cloud roles after our 16.5 release (~May 2016). After the 16.5 release, administrators will no longer be able to add members to roles using LSGs or DLs. For additional information regarding Active Directory group types, please refer to the following Microsoft Article.

After release of 16.7, LSGs and DLs will no longer be supported for managing security with existing Centrify roles - only global or universal security groups are supported. Existing LSGs and DLs must be converted or created new to prevent user impact.

This change does not impact Centrify cloud-based user accounts or Office 365 resource object provisioning such as contacts, groups and distribution lists when using Hybrid mode.

          Application Impact:
  • Apps disappearing from view in the user portal. Users may be unable to access applications 
  • Password prompts for rich mail clients or mobile devices. Users may experience prompts for login credentials and attempts to login may fail 
  • Stored credentials for apps may be lost of Role membership is changed, such as adding a new security group. It is recommended to convert existing unsupported group types nested within the Role to prevent this scenario
  • Users may be prompted to enter stored application credentials more than once in the Centrify User Portal
  • Application Workflow (App+ Edition) may fail
          Authentication Impact:
  • Login to Centrify User Portal with Active Directory user could be impacted if not using the “Everybody” Role
  • Login to Centrify Cloud Manager with Active Directory user may fail if sysadmin Role contains unsupported group type
  • MFA policies may fail to apply
  • User account recovery options such as password reset or account unlock may fail to apply
  • SP-initiated login to web applications may fail
          Mobile Device Impact:
  • Users may be unable to enroll mobile devices
  • Group policy applied to existing mobile devices may be removed - this includes restrictions and configuration profiles for Exchange ActiveSync, VPN and Wi-Fi. 
  • Mobile group policy may fail to apply/update
  • User may receive password prompts for Exchange ActiveSync accounts
  • Application access & SSO may fail
  • Use of Centrify mobile authenticator may fail

Purpose of the change:

Centrify is optimizing the Cloud Connector service to greatly improve performance across all Active Directory environments, and deliver better responsiveness. We are making significant enhancements "under the hood" through this development period, however the user interface will remain unchanged.

Does this change affect me?

If your organization is not using distribution lists to manage Centrify cloud roles and only use universal or global security groups, no additional actions are needed as this configuration is fully supported. To determine if your tenant may be affected, please review the group example image and action steps below. The group options used with Centrify roles should use scope of Universal or Global and the group type should be Security.

User-added image  User-added image

What actions are required by customers?

Centrify roles with nested distribution lists as members will need to be converted or updated to security groups prior to release of 16.7 (~July 2016). Administrators may  perform manual conversion or create new groups as needed or can use a utility provided by Centrify.

To assist customers, Centrify has created a utility that will allow existing unsupported group types to be identified and provide administrators a method to convert or clone/copy the group as desired.

Use of this utility is not required and offered as a convenience. The utility is attached at the bottom of this article and supports the following commands:
  • help: Shows usage and help
  • findGroups: Identifies unsupported groups
  • convertGroup: Converts existing group to universal security group
  • cloneGroup: Copies group members from existing group to new universal group

Requirements to run the utility:
  • Utility must be run on a 64 bit machine joined to Active Directory linked with the cloud tenant.
  • .NET framework version (version 4.5 or greater) must be installed.
  • Cloud tenant URL or service URL. (example:
  • Tenant ID. Administrators and users can view the tenant ID by logging into the cloud manager or user portal and then clicking username on top right and selecting 'About'. (example: AAA0123)
  • Any admin user name and password for the tenant. The utility only needs read access to the cloud service - see the online help section Managing Roles.
  • User running the utility must have AD domain admin permissions or equivalent to create new groups or convert group types.
  • When launching the command prompt to execute the commands, be sure to "Run as Administrator"

Onetime utility setup:

Download the attached .zip file and extract the GroupFinderTool folder and it's contents to a local drive. After the utility and its associated binaries have been extracted, open and edit the GroupUtility.exe.config file at the following location:


Locate the <appSettings> section within the config file and fill in the values below using your specific tenant information for the following parameters:
  • Set value of cloudServiceHost key to cloud service URL. Example: or
  • Set value of tenantId key with your customer Id. You can get your customer Id by logging on to cloud and then clicking username on top right and then clicking About. Example: AAB1234
  • Set value of userName with your tenant admin username. The username must be at least a read-only administrator of your tenant. Administrators will be prompted for password of this user running the utility.  
  • After performing the required edits, be sure to save the config file.

   Config file example:

    <!--Fill in these values for sure-->

    <!-- Cloud service url or your tenant URL. -->
    <!-- Example of cloud service url: -->
    <!-- Example of tenant Url: or -->
    <!-- Example: <add key="cloudServiceHost" value=""/>-->
    <add key="cloudServiceHost" value=""/>

    <!-- Your tenant id. Ex: ABC1234 -->
    <!--Example: <add key="tenantId" value="ABC1234"/>-->
    <add key="tenantId" value="ql355"/>

    <!-- Your cloud admin user. Ex:  -->
    <!-- Example:<add key="userName" value=""/>-->
    <add key="userName" value="joeadmin@centrifytls.test"/>
    <!-- we will ask for password -->

Locating Role distribution groups using the findGroups command:

The findGroups command scans existing Centrify roles and lists unsupported AD groups. This command will display a summary with the role, AD objectGuid and AD distinguishedName of each unsupported group.

Note: To scan role membership, the admin account specified in in 'Onetime utility Setup' above must have admin read access permissions (full admin access is not required) to your cloud tenant and will be prompted for password when running the utility.

Usage Example: GroupUtility.exe findGroups

The results will be displayed in the command window along with a summary at the bottom of the report. The output is also logged at \GroupFinderTool\Install\Binaries\GroupUtility.log. After the resulting list of unsupported groups is displayed as shown in the below image, administrators can use the convertGroup or cloneGroup command examples below for corrective actions.

   FindGroups Output example:

The following report indicates groups, Accounting DL, Finance DL and Executives DL need action and are members of roles named Accounting, Finance and Executives.

2016-05-18 20:47:22,816 [1|(null)|(null)|(null)|DEBUG] AdUtility: Source group dn: CN=Accounting DL,CN=Users,DC=centtls,DC=com
2016-05-18 20:47:22,816 [1|(null)|(null)|(null)|DEBUG] AdUtility: After fixup - Source group dn: LDAP://CN=Accounting DL,CN=Users,DC=centtls,DC=com
2016-05-18 20:47:22,832 [1|(null)|(null)|(null)|DEBUG] AdUtility: Is Group at DN a supported group? False
2016-05-18 20:47:22,847 [1|(null)|(null)|(null)|DEBUG] AdUtility: Source group dn: CN=Executives DL,CN=Users,DC=centtls,DC=com
2016-05-18 20:47:22,847 [1|(null)|(null)|(null)|DEBUG] AdUtility: After fixup - Source group dn: LDAP://CN=Executives DL,CN=Users,DC=centtls,DC=com
2016-05-18 20:47:22,863 [1|(null)|(null)|(null)|DEBUG] AdUtility: Is Group at DN a supported group? False
2016-05-18 20:47:22,863 [1|(null)|(null)|(null)|DEBUG] AdUtility: Source group dn: CN=Finance DL,CN=Users,DC=centtls,DC=com
2016-05-18 20:47:22,863 [1|(null)|(null)|(null)|DEBUG] AdUtility: After fixup - Source group dn: LDAP://CN=Finance DL,CN=Users,DC=centtls,DC=com
2016-05-18 20:47:22,879 [1|(null)|(null)|(null)|DEBUG] AdUtility: Is Group at DN a supported group? False
2016-05-18 20:47:22,879 [1|(null)|(null)|(null)|INFO ] GroupUtility: Group c6555b7f-1ff6-4007-b182-a496b2514fb5(CN=Finance DL,CN=Users,DC=centtls,DC=com) requires conversion or cloning
2016-05-18 20:47:22,879 [1|(null)|(null)|(null)|INFO ] GroupUtility: ============= Summary for findGroups =======
2016-05-18 20:47:22,879 [1|(null)|(null)|(null)|INFO ] GroupUtility:    
2016-05-18 20:47:22,879 [1|(null)|(null)|(null)|INFO ] GroupUtility: Group principal: 6f78a388-9d82-485a-9561-3381c25faf1d
2016-05-18 20:47:22,879 [1|(null)|(null)|(null)|INFO ] GroupUtility:   Member of roles: Accounting
2016-05-18 20:47:22,879 [1|(null)|(null)|(null)|INFO ] GroupUtility:   Summary message: *ACTION NEEDED*: Run convertGroup or cloneGroup or migrate manually.
2016-05-18 20:47:22,879 [1|(null)|(null)|(null)|INFO ] GroupUtility:    
2016-05-18 20:47:22,879 [1|(null)|(null)|(null)|INFO ] GroupUtility: Group principal: e9d0d1dd-f71a-4a7e-8ab9-9f049c027e72
2016-05-18 20:47:22,879 [1|(null)|(null)|(null)|INFO ] GroupUtility:   Member of roles: Executives
2016-05-18 20:47:22,879 [1|(null)|(null)|(null)|INFO ] GroupUtility:   Summary message: *ACTION NEEDED*: Run convertGroup or cloneGroup or migrate manually.
2016-05-18 20:47:22,879 [1|(null)|(null)|(null)|INFO ] GroupUtility:    
2016-05-18 20:47:22,879 [1|(null)|(null)|(null)|INFO ] GroupUtility: Group principal: c6555b7f-1ff6-4007-b182-a496b2514fb5
2016-05-18 20:47:22,879 [1|(null)|(null)|(null)|INFO ] GroupUtility:   Member of roles: Finance
2016-05-18 20:47:22,879 [1|(null)|(null)|(null)|INFO ] GroupUtility:   Summary message: *ACTION NEEDED*: Run convertGroup or cloneGroup or migrate manually.

Converting Role distribution groups using the convertGroup command:

Use the convertGroup command to convert an unsupported AD group nested within a Centrify Role to a universal security group. This retains the original group name all group members
  • Usage syntax: GroupUtility.exe convertGroup <DN of group to be converted>
  • Example: GroupUtility.exe convertGroup "CN=UnsupportedGroup,CN=Users,DC=mydomain,DC=com"

Note: Not all groups can be converted to universal security groups. As example, Domain local groups which contain other domain local groups as its group members cannot be converted to Universal groups. 

If the distribution group to be converted is used by Exchange, Exchange configuration must be updated to reflect the change. More details are available at the following Microsoft URL:
   ConvertGroup Output example:

User-added image

Cloning Role distribution groups using cloneGroup command:

Use the cloneGroup command to clone/copy an unsupported AD group nested within a Centrify Role to a universal security group Use this option when convertGroup cannot be used for any reason. The new group created is a universal security group and all users from the distribution group are recursively copied to the new security group.
  • Usage: GroupUtility.exe cloneGroup <DN of old group> <OU location for new group> < SamAccountName for new group>
  • Example: GroupUtility.exe cloneGroup "CN=UnsupportedGroup,CN=Users,DC=mydomain,DC=com" "CN=Users,DC=mydomain,DC=com" "NewGroupSamAccountName"
Note: After new group is created and populated, make sure to add this group to the role and click "Save" before removing the original distribution group from the role.

   CloneGroup Output example:

User-added image

A video demo of this tool can be viewed below.


Still have questions? Click here to log a technical support case, or collaborate with your peers in Centrify's Online Community.