GDAP bulk migration tool

Appropriate roles: Global admin | User management admin | Admin agent | Sales agent

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 (accessed) or inactive (not accessed) in the last 90 days, DAP relationship between the CSP and their customer.

The bulk migration tool has the following features:

  • Open-source .NET console tool that uses open-source .NET SDK
  • Supports comma separated (.csv) and JSON (.json) file formats for setting up data for migration.
  • No code changes required and it can be launched out of the box with a .NET command.
  • Code is extensible and can be enhanced if partners need it to be.
  • Extensive logging that can help troubleshoot issues.

Who is this tool for? 

Direct bill partners, indirect providers, and indirect resellers transacting through the Cloud Solution Provider (CSP) program.

Prerequisites

  • Auto-approval of GDAP relationship only works if there exists an active or inactive DAP 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.

  • 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-main\GBM.

    Screenshot of GDAP bulk migration tool download.

  • The partner tenant should have onboarded the GDAP Enterprise App ID that represents the resource 'https://api.partnercustomeradministration.microsoft.com'. This process is documented in List delegated admin customers steps one and two, and in the Bulk migration tool FAQ.

  • The partner tenant admin will have to provide consent on behalf of the organization for the tool to be able to call GDAP APIs and perform operations.

  • The GDAP app service principal is required. The GDAP bulk migration tool will attempt to add this principal on your behalf. If you see the error below, then the current user doesn't have Global Admin privileges, which are required when adding the GDAP app service principle. Once the GDAP app service principal has been added, any user in the AdminAgents security group may run the tool. The following dialog box is shown when the user does not have Global Admin.

    Screenshot of form with prerequisite options.

    Selecting “Return to the application without granting consent” generates the following error in the tool:

    Screenshot of console with prerequisite error.

Starting the GDAP bulk migration tool

To run the tool, open a Command Prompt, change the directory into the folder './GBM' and 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.

Screenshot of console with file options.

Upon selection of your preferred file format, you'll be presented with the main menu.

Screenshot of console with menu options.

Overview of menu operations

Download Operations

  • Download eligible customers list – Retrieves all the Partners customers that have an active or inactive 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.

    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 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)

    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.

Screenshot of file explorer downloads folder.

The following files: ADRoles.csv, customers.csv, and securityGroup.csv contain all of 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.

Screenshot of file explorer operations folder.

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.

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

Screenshot of successful authentication message.

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.

Screenshot of customers csv file.

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

Screenshot of ADRoles csv file.

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.

Screenshot of console option seven.

The output of the GDAP relationships will live in the following file .\GBM\GDAPBulkMigration\operations\gdapRelationship\gdapRelationship.csv

Screenshot of GDAP relationship csv file.

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

    Tip

    You might need to enclose each CommaSeparatedRoles value in qutotation marks ("").

    Example: securityGroup.csv

    Screenshot of security group csv file.

    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 9. Create Security Group-Role Assignment(s) by selecting “9”, pressing enter, and then answering the confirmation with “y” or “Y” to continue.

    Screenshot of console option nine.

    The output and status of the creation of the security group-role assignments will be available in the following file \GDAPBulkMigration\operations\ accessAssignment\accessAssignment.csv

    Screenshot of access assignment csv.

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

  3. To update the accessAssignment.csv file, periodically run the option 10. Refresh Security Group-Role Assignment status.

    Screenshot of console option 10.

    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.

This file consists of the following columns:

  • Id – Represents the unique identifier of the GDAP relationship.
  • CustomerDelegatedAdminRelationshipId – Represents the unique identifier linked to the customer.

    Note

    CustomerDelegatedAdminRelationshipId may be blank if you created a generic GDAP relationship request.

  • DisplayName – Represents the unique GDAP relationship name provided by the CSP
  • TenantId – CSP’s tenant ID
  • DisplayName – CSP’s customer’s name.

    Note

    In some cases, DisplayName may be blank and is a known issue. The TenantId should always be populated and represent the customer’s tenant id.

  • TenantId – CSP’s customer’s tenant ID.
  • Duration – Number of days this relationship will be active.
  • Status – The status of the relationship: ApprovalPending, Terminated, Approved, or Active.
  • CreatedDateTime – When the relationship request was created.
  • ActivatedDateTime – When the relationship request was accepted or activated.
  • LastModifiedDateTime – When the relationship request was last modified.
  • EndDateTime – When the relationship request will end.
  • VersionStamp – Version number.

Next steps