Dynamics 365 Business Central: transitioning from Delegated Admins to Granular Delegated Admins

At the beginning of this year I’ve shared a post explaining the new Granular Delegated Administrator privileges for Microsoft 365 and Dynamics 365.

In a recent announcement, Microsoft has shared the final plan on transitioning from Delegated Admins Privileges (DAP) to Granular Delegated Admins Privileges (GDAP) and as a Dynamics 365 Business Central partner I think you need to be aware of these plans.

These are the important milestones to remember:

• Microsoft will stop creating DAPs when a new customer or reseller relationship is created. Partners will need to update their process for acquiring new CSP customers in order to include requesting GDAP permissions from customers.
• Microsoft will start removing DAPs that have been inactive for 90 or more days. If admin privileges are needed, the partner should create a GDAP relationship with the customer with the appropriate level of access and time they require to manage their customer’s service.
• Microsoft will transition active DAP connections to least privileged GDAP roles starting October 31, 2022.

In order to help on transitioning DAP to GDAP, Microsoft has released a GDAP bulk migration tool to create GDAP relationship with Azure Active Directory (AD) roles. This tool allows partners with existing DAP relationships that were granted by customers to upgrade to GDAP relationships with Azure AD roles. This tool will be available until October 31, 2022, after which customers will need to resume approving all GDAP relationship requests. Partners should use this tool to upgrade the delegated admin privileges (DAP) relationships they are using to GDAP ahead of the upcoming transition milestones previously explained.

The GDAP Bulk Migration Tool is available on Github here.

To start using this tool, download it from the Github repo as a zip file and extract it in a local folder. Then open a command prompt, go into the GBM subfolder and enter “dotnet run” in order to compile and execute the project (it requires .NET 6.0).

The first time you execute one of the tools’ operations, a browser window will be launched asking you to provide the sign-in credentials that you use when logging into Partner Center. You need to execute the tool as a partner tenant admin (you need to have Global Admin privileges in your partner’s tenant). Once the GDAP app service principal has been added, any user in the AdminAgents security group may run the tool:

Check “Consent on behalf of your organization” flag and click Accept.

When the grant is established, the tool asks you to select the file format you prefer the tool to use during downloads and execution: JSON or CSV (select what you want):

Then, the main menu is presented:

Here you have a set of possible operations that you can do:

Download Operations

• Download eligible customers list: Retrieves all the Partners customers that have an active DAP account. You’ll need to modify this file prior to running option 7. Create GDAP Relationships.
• Download eligible customers for very large list (compressed): Same as above, saved in a GZIP file format. This operation is suitable for any CSP that has 300 plus customers.
• Download Example Azure AD Roles: Creates an example file: ADRoles(.csv or .json) that can be used when creating the GDAP relationship. You’ll want to modify this file and only include the roles that should be assigned to the GDAP relationship. This modified file will be used when running option 7. Create GDAP Relationship(s) and option 9. Create Security Group-Role Assignments.
• Download Partner Tenant’s Security Groups: Retrieves all of the current partner’s Azure AD security groups. You’ll modify this file to include only the security groups that will be associated with the GDAP relationships. This modified file will be used when running option 9. Create Security Group-Role Assignments.
• Download existing GDAP relationship(s): Retrieves all of the current GDAP relationships along with their status. This file can be reviewed to understand any anomalies that may be present and help in trouble shooting errors. (This download operation isn’t required).

GDAP Relationship Operations

• One Flow generation: This option executes operations 7 followed by operation 9.
• Create GDAP Relationship(s): This option uses the modified customer list and Azure Roles file downloaded using option 1. Download eligible customers list and option 3. Download Azure AD Roles, to create the GDAP relationship.
• Refresh GDAP Relationship(s) status: The creation of the GDAP relationships isn’t synchronous, therefore, the tool may return before all the backend processing has completed. Periodically running the tool will update the status of the GDAP relationships. Don’t proceed until all status codes have been updated to an “Active” status.

Provision Security Group Operations

• Create Security Group-Role Assignment(s): permits you to associate one or more security groups with one or more roles in the customer tenant that were specified in the GDAP relationship created for customers in Option 7.
• Refresh Security Group-Role Assignment status: The assignment of the security groups isn’t synchronous, therefore, the tool may return before all the backend processing has completed. Periodically running the tool will update the status of the bulk migration session.

To check for what customers you have a Delegated Administrator Privileges (DAP) relationship, you can execute option 1. When started, the tool creates a GDAPBulkMigration\downloads folder (under the GBM folder) that contains the output of the operation:

These are the customers where I have to work on migrating DAP to GDAP.

You start a DAP to GDAP migration, you need to execute operations 1,3,4,5:

and this set of operations creates 4 files in your .GBM\GDAPBulkMigration\downloads folder:

The GDAP bulk migration tool sources its data from the following location: ./GBM/GDAPBulkMigration/operations for each bulk migration session.

The ADRoles.csv and securityGroup.csv files should be edited versions of the files that were previously downloaded (into the /downloads folder). They should contain the specific Azure AD roles and security groups per your requirements. In most cases, you will edit these files once and leave them as is in the operations folder. For more complex scenarios, you may need to update these files per session as well.

The process of creating new GDAP relationships requires 2 input files that must live in a subdirectory named ./GBM/GDAPBulkMigration/operations:

customers (.csv or .json): This file contains the list of customers that will have a new GDAP relationship created. This file has following 5 columns:

• Name: The unique name per partner tenant that will be used to name the newly created GDAP relationship. Each name has a maximum length of 50 characters and allows alphanumeric, dashes, and underscores.
• PartnerTenantId: The tenant ID associated with the customer tenants that will be associated with the newly created GDAP account.
• CustomerTenantId: The associated customer tenant.
• OrganizationDisplayName: The customer’s organization name.
• Duration: The number of days (1 to 730) that the GDAP relationship will remain valid.

An example of the output file:

ADRoles (.csv or .json): This file contains the list of the Azure AD Roles that will be assigned to the GDAP relationship. This file consists of the following 3 columns:

• Id: Represents the unique identifier for the specific Azure AD role you’re adding.
• Name: Name of the Azure AD role.
• Description: Description of the Azure AD role.

Example of the file:

You can refer to permissions reference for a complete list of role templates that can be used in the setup file ADRoles.csv during relationship creation and security group assignments.

When the two files are prepared, execute the operation 7 – Create GDAP Relationship(s):

This operation creates the following file: .\GBM\GDAPBulkMigration\operations\gdapRelationship\gdapRelationship.csv that contains the details of the created GDAP relationship.

It’s important to note that the status of the created GDAP Relationships will start out as “Approved”. Before continuing with the Provision Security Groups operation, you must validate that the status has changed to Active for all of the GDAP relationships that were created (the status is updated by a server-side process). Typically, it may take up to five minutes before getting updated from ‘Approved’ to ‘Active’ for creating relationships and assignment operations.

Now you need to perform the Provision Security Groups related operations.

For this, edit the securityGroup (.csv or .json) file exported by executing the command 4. This file contains the security groups and roles that you wish to assign and associate with the GDAP relationships and consists of the following 3 columns:

• Id: The unique ID assigned to the partner’s security group.
• DisplayName: The friendly name of the security group.
• CommaSeperatedRoles: A list that must contain one or more (separated by commas) of the Azure AD role IDs that were defined in the ADRoles.csv file that were assigned to the newly created GDAP relationships.

When the securityGroup file is ready and placed into the /operations folder, run the operation 9. Create Security Group-Role Assignment(s):

This operation creates a \GDAPBulkMigration\operations\ accessAssignment\accessAssignment.csv file with the output and status of the creation of the security group-role assignments. The Status field should be Active.

Please remember that the tool doesn’t support updating GDAP role assignments. To update the assignments, you need to go to the Microsoft Partner Center > Customers > Administer, find the customer, terminate the incorrect relationships and then run the tool again with updated role assignments.