GDAP API: Express Customer Transition

Introduction

This article is describing our current GDAP API endpoint parameters, payloads and which call methods to use for specific tasks, and how to combine these workflows in C# implementation for Express Transition flow which moves some of the labor-intensive tasks to the API side.

Description

Express Transition flow is intended for a transition that requires a less granular approach. In this scenario, you only need to make 1 API call per customer without having the template configured or saved in the back-end as long as the payload contains valid data, such as the customer tenant Id, proper role IDs, and descriptions.

When you make a call to this API following actions are taking place on the back-end.

1. Validation of the payload

• Role IDs are matched with actual AAD roles, foreign Id's are not allowed
• Role Duplicates
• Bearer token claims vs. providerId that is provided in the payload
• Duration

2. Security Group Provisioning

• Checks if there are security groups on your tenant configured vs. the role definitions provided in the payload - if not found, security groups are provisioned.
• In an express transition case, the owner of new potential security groups becomes the user account that is used for signing the graph consent.
• Admin Agent security group is automatically nested under newly created security groups.

3. Creation of GDAP Relationship

• GDAP Relationship is created on behalf of the customer and activated (may take up to 1 minute)
• Once the relationship is active, access assignments are created from applied roles to security groups

Resource Links

Swagger UI - https://dev-gdap.azurewebsites.net/api/swagger/ui

Base URL: https://dev-gdap.azurewebsites.net/api/

API:   Express Customer Transition
Url: {baseurl}ExpressTransition
Method: POST

Body

{
    "PartnerId": "918c6a1a-339c-43ec-a8ea-e0343eea7e0b",
    "TemplateId": null,
    "CustomerId": "109256e3-b385-4eb9-8151-51d29faea256",
    "AppliedRoles": [
        {
            "Id": "f023fd81-a637-4b56-95fd-791ac0226033",
            "Name": "Service support administrator",
            "Description": "Can read service health information and manage support tickets."
        },
        {
            "Id": "eb1f4a8d-243a-41f0-9fbd-c7cdf6c5ef7c",
            "Name": "Insights administrator",
            "Description": "Has administrative access in the Insights app."
        },
        {
            "Id": "d37c8bed-0711-4417-ba38-b4abe66ce4c2",
            "Name": "Network administrator",
            "Description": "Can manage network locations and review enterprise network design insights for Microsoft 365 Software as a Service applications."
        },
        {
            "Id": "194ae4cb-b126-40b2-bd5b-6091b380977d",
            "Name": "Security administrator",
            "Description": "Can read security information and reports  and manage configuration in Azure AD and Office 365."
        },
        {
            "Id": "fe930be7-5e62-47db-91af-98c3a49a38b1",
            "Name": "User administrator",
            "Description": "Can manage all aspects of users and groups  including resetting passwords for limited admins."
        },
        {
            "Id": "fdd7a751-b60b-444a-984c-02652fe8fa1c",
            "Name": "Groups administrator",
            "Description": "Can manage all aspects of groups and group settings like naming and expiration policies."
        }
    ],
    "TemplateName": "Can be any name here",
    "Duration": "P2Y"
}

Headers

Example:
POST - https://dev-gdap.azurewebsites.net/api/ExpressTransition

JSON Response 1 (If access is valid and the account has permissions to the provided TenantId in template) :

{
    "Result": "Accepted",
    "Message": "Template data parsed and verfied, security groups created and customer migrated. Customer Id: 109256e3-b385-4eb9-8151-51d29faea256",
    "SecurityGroups": [
        "Group Already Exists: CSP-SG Service support administrator ",
        "Group Already Exists: CSP-SG Insights administrator ",
        "Group Already Exists: CSP-SG Network administrator ",
        "Group Already Exists: CSP-SG Security administrator ",
        "Group Already Exists: CSP-SG User administrator ",
        "Group Already Exists: CSP-SG Groups administrator "
    ],
    "assignmentResults": [
        "Access Role Id Assigned Successfully: f023fd81-a637-4b56-95fd-791ac0226033",
        "Access Role Id Assigned Successfully: eb1f4a8d-243a-41f0-9fbd-c7cdf6c5ef7c",
        "Access Role Id Assigned Successfully: d37c8bed-0711-4417-ba38-b4abe66ce4c2",
        "Access Role Id Assigned Successfully: 194ae4cb-b126-40b2-bd5b-6091b380977d",
        "Access Role Id Assigned Successfully: fe930be7-5e62-47db-91af-98c3a49a38b1",
        "Access Role Id Assigned Successfully: fdd7a751-b60b-444a-984c-02652fe8fa1c"
    ]
}

JSON Response 2 (If the access token is not valid or lacks permissions for the call):

null

Response type will default to - 401 (Unauthorized)

C# Method Example:

public async Task<string> ExpressTransition(string baseUrl, string bearer, string templateBody)
{
    string result = string.Empty;
    string uri = $"{baseUrl}ExpressTransition";
    HttpWebRequest request = (HttpWebRequest)WebRequest.Create(uri);
    request.Method = "POST";
    request.Headers.Add("Authorization", $"Bearer {bearer}");
    request.Accept = "application/json";
    request.ContentType = "application/json";
    request.AutomaticDecompression = DecompressionMethods.GZip | DecompressionMethods.Deflate;
    request.ContentLength = templateBody.Length;

    using (var streamWriter = new StreamWriter(request.GetRequestStream()))
    {
        streamWriter.Write(templateBody);
    }
    var httpResponse = (HttpWebResponse)await request.GetResponseAsync();
    using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
    {
        result = streamReader.ReadToEnd();
    }
    return result;
}

Calling this method from code:

var publish = await gdapTemplateOps.ExpressTransition(CurrentBaseUrl, bearerToken.access_token, templatePayload);