Something a bit different this month. I’m getting down in the weeds and satisfying the inner geek.

gdpa1

 

Cyber Security Expert: One who does precision guesswork based on unreliable data provided by those of questionable knowledge. I love that quote and after using this I’m tempted to add a definition of Tool.

 

Shout out to Ryan at CommandIT for his Assistance and Input.

Disclaimer: This script is supplied as is for you to determine suitability, Dicker Data, Microsoft, and the author accept no responsibility for anything contained or omitted in this article. We strongly recommend that you test against a non-production tenant before proceeding.

Original script and article are available from the following Microsoft article. We have added to this and clarified guidance.

https://docs.microsoft.com/en-us/partner-center/gdap-bulk-migration-tool?wt.mc_id=OCPM_NN_EM_PCN_PC_GL_Learnmore

The DAP to GDAP bulk migration tool enables partners to create new GDAP relationships with implied customer consent. Implied customer consent means there's a pre-existing active DAP relationship between the CSP and their customer.

This tool is designed for direct bill partners and indirect providers transacting through the Cloud Solution Provider (CSP) program.

Prerequisites

  • Auto-approval of GDAP relationship only works if there exists an active or inactive DAP (global Admin) between the partner and the customer.

  • Partner accounts must be MFA (Azure multi-factor authentication) enabled because all GDAP APIs now enforce MFA. Add MFA if it’s not already added by visiting Mandating MFA for your partner tenant.

  • To build and run the GDAP bulk migration tool, you must have the .NET 6.0 SDK installed on the host machine.


Install .net SDK by using one of the methods below. Ryan used the free Visual studio while I used the PowerShell (which didn’t work) then the Windows installer which worked.

gdap2

After installing, Test that dotnet is installed and registered correctly by typing dotnet in a PowerShell window

gdap3

 

  • Download the GDAP bulk migration tool source from GitHub. Extract the files into a local working folder. Once complete, you should have a folder named: PartnerCenter-GDAPTransition-mainGBM

 

 

 

gdap4

  • The GDAP app service principal is required. The GDAP bulk migration tool will attempt to add this principal on your behalf. Once the GDAP app service principal has been added, any user in the Admi Agents security group may run the tool.

gdap5

 

 

Starting the GDAP bulk migration tool

To run the tool, open a PowerShell Command Prompt,

  1.  Change the directory into the folder './GBM' For example “CD C:GDAPTOOLPartnerCenter-GDAPTransition-mainPartnerCenter-GDAPTransition-mainGBM”

  2.  Enter 'dotnet run'.

Once the build (if necessary) finishes, you'll be prompted to select the file format you prefer the tool to use during downloads and execution: JSON or CSV. Enter the number corresponding to your choice.

gdap6

Upon selection of your preferred file format, you'll be presented with the main menu. For this article we are using CSV format.

 

Overview of menu operations

Download Operations

 

gdap7

 

  • 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 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.

Note

Users must be added to security groups separately, which is not in the scope of this tool.

  • Download existing GDAP relationship(s) – Retrieves all 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)

Important

You must 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. The partner may add users to the security groups beforehand or add them later to grant access to the customers' environment for administration, which is outside the scope of this tool.

  • 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.

 

Bulk migration session

The process of migrating customer DAP accounts to GDAP accounts must be in the following order for each batch of customers that are being migrated.

For example, given a total of 1,000 customers and a batch size of 300 customers per migration, you could divide your customers into three batches of 300, followed by one batch of 100. For each batch of customers, you would execute the first scenario: Creating GDAP Relationships followed by the second scenario – Provisioning Security Groups, in that order.

 

Preparation

The GDAP bulk migration tool has a section named Download Operations which has been provided to help enable and accelerate the migration. All downloaded files will be placed in the following location: ./GBM/GDAPBulkMigration/downloads.

gdap8

 

The following files: ADRoles.csv, customers.csv, and securityGroup.csv contain all the records for each respective grouping and can be used as data sources when creating similar name files used during the migration.
The GDAP bulk migration tool sources its data from the following location: ./GBM/GDAPBulkMigration/operations for each bulk migration session.

gdap9

Given our batch size of 300 customers per session, we would need to create four different customer.csv files, three with 300 customers, and a final file of 100 customers, updating the customer.csv file in the operations folder four times for each session.

Important

The ADRoles.csv and securityGroup.csv files should be edited versions of the files that were previously downloaded. 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. I have included role template ID’s and role name in this sheet https://dickerdata-my.sharepoint.com/:x:/g/personal/paul_caldwell_dickerdata_co_nz/EbKAVGnkKyNPrPOkS5d6HDAB3Wy96jx_dGNNDT4uTER1HQ?e=LczGhZ I generated this by creating a new user assigning roles then exporting the role ID’s to a csv file which was then added to my operations folder and renamed to “ADroles.csv” I included a Global admin only for test please do not try to assign this role using the tool.

 

Authentication

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 Centre. Check the FAQ for the one-time consent that needs to be provided by your tenant admin.

Upon successful authentication, you'll see the following message. You should close the browser tab and return to the console application.

gdap10

Creating GDAP relationships

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

File – customers (.csv or .json) This file contains the list of customers that will have a new GDAP relationship created.

This file consists of the following five 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.

Example: customers.csv

The highlighted columns aren't populated during the corresponding download customer list operation, but they must be provided before running the tool.

gdap11

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 three 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: ADRoles.csv

gdap12

For more information, see GDAP role guidance and Azure AD built-in roles.

Important

Validate that the two files (customer.csv and ADRoles.csv) have been properly prepared before proceeding. See the section Preparation for details.

Once validated, then you are ready to move on to the next step.

Run the operation 7. Create GDAP Relationship(s) by selecting “7", pressing enter, and then answering the confirmation with “y” or “Y” to continue.

gdap13

The output of the GDAP relationships will live in the following file .GBMGDAPBulkMigrationoperationsgdapRelationshipgdapRelationship.csv

gdap14

 

Important

The status of the creation 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 the GDAP relationships that were created. The status is updated by a server-side process.

To update the gdapRelationship.csv file, periodically run the option 8. Refresh GDAP Relationship(s) status.

You may have several GDAP relationships that have an error where the status isn't Active. You can choose to filter out those GDAP relationships that have failed by removing them from the customers.csv file, ensuring that only relationships with a status of Active are present. You’re now ready to move on to the Provision Security Groups operation.

Make sure you save any relationships that have errored for further investigation.

Provision security groups

  1. Identify or create the Azure AD security groups you plan on associating with the GDAP relationships. A security group is required and is how you grant your employees access to administer your customers' environment.


File – securityGroup (.csv or .json) This file contains the security groups and roles that you wish to assign and associate with the GDAP relationships that were created and activated in the first scenario.

This file consists of the following three 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.

Example: securityGroup.csv

gdap15

Important

Validate that the two files (customer.csv and securityGroup.csv) have been properly prepared before proceeding. See the section named Preparation for details. Once validated, you are ready to move on to the next step.


2. Run the Operation Create Security Group-Role Assignment(s) by selecting “9”, pressing enter, and then answering the confirmation with “y” or “Y” to continue.

gdap16

The output and status of the creation of the security group-role assignments will be available in the following file GDAPBulkMigrationoperations accessAssignmentaccessAssignment.csv

gdap17

Confirm that the assignment statuses have a value of “Active”.

              3. To update the csv file, periodically run the option 10. Refresh GDAP Relationship(s) status.

gdap18

You can now repeat the above steps for the remainder of your DAP to GDAP transitions.

 

Additional file details

File – ExistingGdapRelationship (.csv or .json) This file will contain the list of all of the partner’s GDAP relationships.

Summary: This tool does involve a considerable amount of manual work. Assess whether a tenant-by-tenant manual approach will be less time consuming. I estimate that using this tool would take 1-2 hours to complete migration of all tenants.

  1. Download existing relationships

  2. Edit those files in the download folder and move to the operations folder maintain naming conventions

  3. Run operations

  4. Once operations have run you will no longer be able to use this tool as the global admin role will have been removed.