Enabling the Secure Application Model framework

Microsoft is introducing a secure, scalable framework for authenticating cloud solution provider (CSP) partners and control panel vendors (CPV) through the Microsoft Azure Active Directory Multi-Factor Authentication (MFA) architecture.

You can use the new model to elevate security for Partner Center API integration calls. This will help all parties (including Microsoft, CSP partners, and CPVs) to protect their infrastructure and customer data from security risks.

The CSP program allows customers to buy Microsoft products and services through the partners. As per the agreement with Microsoft, partners are required to manage the environment for the customers they sell to and provide support. Customers who buy through this channel must place a high amount of trust in the partner they're buying from because the partner business has high-privilege admin access to the customer tenant. 


This article relates to both CSPs and CPVs.


  • A CPV is an independent software vendor that develops apps for use by CSP partners to integrate with Partner Center APIs.
  • A CPV isn't a CSP partner with direct access to Partner Center or APIs.


  • CSP indirect providers and CSP direct partners who are using app ID + user authentication and directly integrate with Partner Center APIs.

Security requirements

For details on security requirements, see Partner Security Requirements.

Secure Application Model

Marketplace applications need to impersonate CSP partner privileges to call Microsoft APIs. Security attacks on these sensitive applications can lead to the compromise of customer data.

For an overview and details of the new authentication framework, see the Secure Application Model framework, which covers principles and best practices to make marketplace applications sustainable and robust from security compromises.


The following overview documents and sample code describe how partners can implement the Secure Application Model framework:


To to make REST calls with the Secure Application Model framework with sample code, follow these steps:

  1. Create a web app

  2. Get an authorization code

  3. Get a refresh token

  4. Get an access token

  5. Make a Partner Center API call


You can use the Partner Center PowerShell module to get an authorization code and a refresh token. You can choose this option in place of steps 2 and 3. For more information, see the PowerShell section and examples.

Create a web app

You must create and register a web app in Partner Center before making REST calls.

  1. Sign in to the Azure portal.

  2. Create an Azure Active Directory (Azure AD) app.

  3. Give delegated application permissions to the following resources, depending on your application's requirements. If necessary, you can add more delegated permissions for application resources.

    1. Microsoft Partner Center (some tenants show this as SampleBECApp)

    2. Azure Management APIs (if you are planning to call Azure APIs)

    3. Windows Azure Active Directory

  4. Make sure that the home URL of your app is set to an endpoint where a live web app is running. This app will need to accept the authorization code from the Azure AD login call. For example, in the example code in the following section, the web app is running at https://localhost:44395/.

  5. Note the following information from your web app's settings in Azure AD:

    • Application ID
    • Application secret


It is recommended to use a certificate as your application secret. However, you can also create an application key in the Azure portal. The sample code in the following section uses an application key.

Get authorization code

You must get an authorization code for your web app to accept from the Azure AD login call:

  1. Log in to Azure AD.

    Be sure to log in with the user account from which you will make Partner Center API calls (such as an admin agent or sales agent account).

  2. Replace Application-Id with your Azure AD app ID (GUID).

  3. When prompted, log in with your user account with MFA configured.

  4. When prompted, enter additional MFA information (phone number or email address) to verify your login.

  5. After you are logged in, the browser will redirect the call to your web app endpoint with your authorization code. For example, the following sample code redirects to https://localhost:44395/.

Authorization code call trace

POST https://localhost:44395/ HTTP/1.1
Origin: https://login.microsoftonline.com
Upgrade-Insecure-Requests: 1
Content-Type: application/x-www-form-urlencoded
Accept: text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8
Referrer: https://login.microsoftonline.com/kmsi
Accept-Encoding: gzip, deflate, br
Accept-Language: en-US,en;q=0.9

code=AuthorizationCodeValue&id_token=IdTokenValue&<rest of properties for state>

Get refresh token

You must then use your authorization code to get a refresh token:

  1. Make a POST call to the Azure AD login endpoint https://login.microsoftonline.com/CSPTenantID/oauth2/token with the authorization code. For an example, see the following sample call.

  2. Note the refresh token that is returned.

  3. Store the refresh token in Azure Key Vault. For more information, see the Key Vault API documentation.


The refresh token must be stored as a secret in Key Vault.

Sample refresh call

Placeholder request:

POST https://login.microsoftonline.com/CSPTenantID/oauth2/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: login.microsoftonline.com
Content-Length: 966
Expect: 100-continue

Request body:


Placeholder response:

HTTP/1.1 200 OK
Cache-Control: no-cache, no-store
Content-Type: application/json; charset=utf-8

Response body:


Get access token

You must obtain an access token before you can make calls to the Partner Center APIs. You must use a refresh token to obtain an access token because access tokens generally have a very limited lifetime (for example, less than an hour).

Placeholder request:

POST https://login.microsoftonline.com/CSPTenantID/oauth2/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: login.microsoftonline.com
Content-Length: 1212
Expect: 100-continue

Request body:

resource=https%3a%2f%2fapi.partnercenter.microsoft.com&client_id=Application-Id &client_secret= Application-Secret&grant_type=refresh_token&refresh_token=RefreshTokenVlaue&scope=openid

Placeholder response:

HTTP/1.1 200 OK
Cache-Control: no-cache, no-store
Content-Type: application/json; charset=utf-8

Response body:


Make Partner Center API calls

You must use your access token to call the Partner Center APIs. See the following example call.

Example Partner Center API call

GET https://api.partnercenter.microsoft.com/v1/customers/CustomerTenantId/users HTTP/1.1
Authorization: Bearer AccessTokenValue
Accept: application/json
X-Locale: en-US
Host: api.partnercenter.microsoft.com


The Partner Center PowerShell module can be used to manage Partner Center resources. It's an open-source project maintained by the partner community and not officially supported by Microsoft. You can get help from the community or open an issue on GitHub if you experience a problem.

You can use the Partner Center PowerShell module to reduce the required infrastructure to exchange an authorization code for an access token. This method is optional for making Partner Center REST calls.

For more information on this process, see Secure App Model PowerShell documentation.

  1. Install the Azure AD and Partner Center PowerShell modules.

    Install-Module AzureAD
    Install-Module PartnerCenter
  2. Use the New-PartnerAccessToken command to perform the consent process and capture the required refresh token.

    $credential = Get-Credential
    $token = New-PartnerAccessToken -ApplicationId 'xxxx-xxxx-xxxx-xxxx' -Scopes 'https://api.partnercenter.microsoft.com/user_impersonation' -ServicePrincipal -Credential $credential -Tenant 'yyyy-yyyy-yyyy-yyyy' -UseAuthorizationCode


    The ServicePrincipal parameter is used with the New-PartnerAccessToken command because an Azure AD app with a type of Web/API is being used. This type of app requires that a client identifier and secret be included in the access token request. When the Get-Credential command is invoked, you will be prompted to enter a username and password. Enter the application identifier as the username. Enter the application secret as the password. When the New-PartnerAccessToken command is invoked, you will be prompted to enter credentials again. Enter the credentials for the service account that you are using. This service account should be a partner account with appropriate permissions.

  3. Copy the refresh token value.

    $token.RefreshToken | clip

You should store the refresh token value in a secure repository, such as Azure Key Vault. For more information on how to leverage the secure application module with PowerShell, see the multi-factor authentication article.