Get Started With Microsoft Cloud Solution Provider Integration

Introduction

The Microsoft Cloud Solution Provider (CSP) program was released in July 2014 to provide a scalable, flexible partner program. CSP is designed to deepen customer relationship and expand business opportunities by allowing partners to:

  • Own and control billing
  • Sell combined offers and services
  • Direct provisioning, management and support

To achieve those capabilities, CSP partners need to integrate their backend systems and business processes with various Microsoft cloud services and processes.

The purpose of this document is to provide guidance for assisting Microsoft Cloud Solution Providers to get started for integrating their business processes and backend systems with Microsoft Cloud Solution Provider program related services and processes.

Understanding Cloud Solution Provider Integration Capabilities

Microsoft provides various APIs to enable CSP partners to integrate their own systems with Microsoft platform. Understanding the purposes and scopes of those APIs is very important to plan, design and architect CSP partners' integrated solutions.

The following list contains the common set of APIs for enabling CSP partners to integrate their own systems with Microsoft various services:

There are more APIs corresponding to various services offered by Microsoft. CSP partners should assess what services they like to offer to their customers and implement the corresponding APIs to integrate with their systems or tools.

Understanding Azure Active Directory Authentication

Those various Microsoft provided APIs are secured by Azure Active Directory. Understanding how Azure Active Directory Authentication and Authorization works is the key to plan, design and implement your integrated solutions.

Azure Active Directory supports OAuth 2.0 Authentication protocol. You can read more about how Azure Active Directory supports OAuth 2.0 at: https://msdn.microsoft.com/en-us/library/azure/dn645545.aspx

Basically there are two options to authenticate to those APIs:

  • Authorization Code Grant Flow: In this flow, the user delegates access to a client application, the application will impersonalize the user to access the APIs.
  • Client Credential Grant Flow: permits a web service (a confidential client) to use its own credentials to authenticate when calling another web service, instead of impersonating a user

When you develop your application to integrate with various Microsoft APIs mentioned above, you need to decide which option to use to authentication your application to access those APIs. In a nutshell, the Authorization Code Grant Flow requires User interactions, and Client Credential Grant Flow doesn't require any user interactions, it is more suitable for automation orientated application.

To use Authorization Code Grant Flow option, you must register a Native Application in your Azure Active Directory, to use Client Credential Grant Flow, you must register a Web Application/Web API in your Azure Active Directory.

Another key concept to pay attention is the Delegated Administration or Admin On Behalf Of, which CSP Partners to manage their customer service on behalf of their customers. Both Office 365 and Microsoft Azure CSP based subscription honor Admin on behalf of, users in CSP Partners AdminAgent group will be automatically provisioned in Office365 and Azure CSP subscription, which will allow users in CSP partner AdminAgent group to manage customer subscription on behalf of customers.

Please note, this only applies to Users, and doesn't apply to application. To allow application to access customer's own Azure Active Directory tenant, the application must be consented. You can read more about consent framework at: https://azure.microsoft.com/en-us/documentation/articles/active-directory-integrating-applications/#overview-of-the-consent-framework

For Azure Resource Management related APIs, to enable application level admin on behalf of, you must use service principal. Please note, in Azure Resource Manager, service principal is scoped at subscription level and therefore you must setup/configure service principal for each subscription you would like to manage. You can read more about how to setup service principal for Azure Resource Manager access here: https://azure.microsoft.com/en-us/documentation/articles/resource-group-authenticate-service-principal/

Note: You need to grant your service principal the appropriate role within your azure subscription to enable to perform the administrative tasks in the sample.

Setup and Configure

To setup your development environment, first you need to register your application in Azure Active Directory. You can log into https://manage.windowsazure.com, navigate to your Active Directory instance, and then select Applications tab, selecting Add Application to register your application as shown below:

Once you registered your application, select Configure tab to configure your application as shown below:

Once you configured your application with appropriate permissions, you should note the Client ID (Application ID) and the Secret/Key.

Then you need to register your application to access CSP Commerce API. You need to log into partner center at https://partnercenter.microsoft.com, select Account Settings, and then select API, click Register as shown below to register your application to access CSP Commerce API.

For testing and development, you should consider to use Integration Sandbox, which will not occur any charges to the services you provisioned during development and testing phase. You can enable Integration Sandbox as shown below in partner center portal.

Please note: The maximum limits for the integration sandbox: 25 test customers, 25 test subscriptions per customer, 25 seats per subscription, and $200 of Azure usage per month.

CSP Integration Samples

A set of samples have been developed to demonstrate how to consume various APIs discussed above to further assist CSP partner's integration efforts. The set of samples is written in C# with Visual Studio 2015 targeting Microsoft .Net Framework 4.5. The samples focus on how to consume various REST APIs to cover broader development platforms across CSP partners instead of using .Net SDKs or PowerShell.

Key Scenarios Covered

The samples cover both Authorization Code Grant Flow and Client Credential Grant Flow to demonstrate different authentication options for obtain Azure Active Directory Access Token.

The samples also illustrate how to integrate CSP Commerce API, Azure Active Directory Graph API, Azure Resource Manager API, and various Azure services related APIs, such as Compute, Storage, Network and Azure SQL Database REST APIs.

The samples demonstrate the following key use cases:

  • Manage Customer
  • Manage Order
  • Manage Subscriptions
  • Manage Users
  • Manage Azure Resources, such as Compute, Storage, Network and SQL Databases under CSP

Structure and Components of the Samples

The sample solution consists of three projects as shown below:

  • Authentication Management: implements the common Authentication functionality covering both Authorization Code Grant Flow and Client Credential Grant Flow options. The component has a common interface defined for encapsulating those authentication option via IAuthManager, the component implements the interface using existing Azure Active Directory Authentication Library, but you can implement your authentication component using raw REST APIs.
  • Cloud Solution Provider Management: this component encapsulates all CSP related REST APIs invocations breaking down to the following:
    • AzureResourceManager: this class implements Azure Resource Management related REST APIs, including Resource Manager REST API, Compute REST API, Storage REST API, Network REST API, and Azure SQL Database REST API. Due to large volume of APIs, the sample only covers the enough APIs to support the key use cases mentioned above.
    • AzureActiveDirectoryManager: this class implements Azure Active Directory Graph REST APIs
    • PartnerCenterManager: this class implements CSP Commerce REST APIs
  • Sample Control Panel: Windows application based on WPF to provide a user interface to exercise the APIs exposed in above two components to illustrate how to integrate those different APIs to build a management portal. The sample control panel illustrates the following key scenarios:
    • CSP Admin: this sample illustrates how CSP admin can perform key administrative tasks by logging in using their Azure Active Directory user account. The sample demonstrates how Authorization Code Grant Flow works and admin on behalf of to enable to manage customers, orders, and customers Azure subscriptions.
    • CSP Customer: this sample demonstrates how customer can log into the application to manage their own services via different APIs, which only limit to their own subscription and tenant.
    • CSP Automation: this sample demonstrates how to implement automation via the Client Credential Grant Flow without any user interaction.

All REST API invocations is implemented using Microsoft HttpClient class, and the implementation is following the common pattern by encapsulating the REST API invocation thru the common method as shown below.

In addition, a custom Delegating Handler is implemented to log all REST API invocations which display all raw http requests and responses.

Build the Samples

The solution is developed using Visual Studio 2015. Once you open the solution in Visual Studio, you can restore all nugget packages to automatically resolve all required dependencies. Then you should be able to build the solution without any missing references.

Running the Samples

Once the solution is successfully built, you can run the sample control panel application as shown below.

First, you need to specify your CSP account information such as tenant id, application Id registered in partner center as shown below:

After you have configured the sample application, you can launch CSP Admin application, and select Login button to login as your CSP admin account, then you can browse all your customers as shown below.

You can also launch the Log Window to view the detailed http requests and responses for all REST API invocations as shown above.

Then you can select Manage Customer to perform various tasks for the selected customer as shown below.

To manage Azure Subscription, click the Manage Azure Subscription button to launch the Manage Azure Subscription window as shown below:

Azure Recovery Services

Recently Microsoft enabled Azure Recovery Services under the new Azure Resource Management based framework, the integration sample was extended with the support for the new Azure Recovery Services under ARM.

The existing Azure Site Recovery services has been renamed to Azure Recovery Services under the new Microsoft.RecoveryServices resource provider. The new Azure Recovery Services resource provider supports the new schema with the following high-level object hierarchy as shown below:

Azure Recovery Services REST API

Following variables have been used in describing URIs

Common request Headers

x-ms-version

Specifies the version of the operation to use for this request. E.g. 1.0

x-ms-client-request-id

Unique identifier for the request e.g. a GUID value.

Content-Type

Set to application/json. This header is not sent in requests that don't have any content, such as all GET calls.

Accept-Language

Specifies the preferred language for the response; all RPs should use this header when generating error messages or client facing text.

Common response headers

x-ms-request-id

Unique request id which can identify the request made to ASR. If a failure occurs that requires the user to contact Microsoft Support, the request id should be provided to Microsoft to assist in tracking and resolving the failure for the request.

Common response headers for async operations

x-ms-request-id

Unique request id which can identify the request made to ASR. If a failure occurs that requires the user to contact Microsoft Support, the request id should be provided to Microsoft to assist in tracking and resolving the failure for the request.

Location

Direct URL of the job object created for the requested operation and can be used to track progress. Like:

https://<endpoint>/subscriptions/{subscriptionId}/{Original-URL-Fo-Request}/operationresults/{operationId}&api-version={api-version}

It supports GET method, which returns 202 http status code if operation is not complete. If the operation is over, it returns 200 with target object as response or 204 with no content. With 202 and 204 status code Location and Retry-After headers will not be returned.

Retry-After

Delay that the client should use when checking for the status of the operation using Location header. This value is an integer and represents the seconds to wait before making another GET call.

Azure-AsyncOperation

URL where the result of the long running operation can be checked; to optionally be used in addition to the Location header. Mostly it will look like:

https://<BaseUrl>/replicationJobs/{jobId}?api-version={api-version}

Error Handling

All handled errors from service are mapped to corresponding HTTP status code and the ServiceError object as described in schema section is retruned in the response.

Sample response.

{
    "code": "ObjectNotFound",
    "message": "The object of type(Microsoft.RecoveryServices.recoveryServicesVaults.Job) and ID(XXX) couldn't be found.",
    "possibleCauses": "Parameters supplied might be incorrect.",
    "recommendedAction": "Correct the parameters and try again.",
    "activityId": "432495d6-2499-4dc5-b128-266c72b778a5"
}

Variables

<endpoint> : It's the ARM endpoint

{SubscriptionId}: It's the subscription ID (GUID) of the customer.

{resourceGroupName}: It's the name of the resource group created by the user under which vaults are created.

{resourceName}: Name of the resource/vault.

{api-version}: api-version of the ASR service client wants to target to.e.g. 2015-08-10.

<BaseUrl> : <endpoint>/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.RecoveryServices/recoveryServicesVaults/{resourceName}

Prerequisites

To enable the new Azure Recovery Services in your subscription, you must register the new Microsoft.RecoveryServices resource provider first. Since the new Azure Recovery Services is still not public released yet, you must enable it before registering the resource provider by running the following PowerShell cmdlet:

Register-AzureRmProviderFeature –FeatureName betaAccess –ProviderNamespace Microsoft.RecoveryServices

After the provider feature is registered, then run the following PowerShell cmdlet to register the resource provider:

Register-AzureRmResourceProvider –ProviderNamespace Microsoft.RecoveryServices

Once the resource provider is registered properly, you should run the sample control panel to manage the Azure Recovery Services as shown below: