Enabling the Secure Application Model framework

Applies to:

  • Partner Center

Microsoft is introducing a secure, scalable framework for authenticating cloud solution provider (CSP) partners and control panel vendors (CPV) through the Microsoft Azure 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.

Scope

This topic concerns the following actors:

  • CPVs
    • A CPV is an independent software vendor that develops apps for use by CSP partners to integrate with Partner Center APIs.
    • A CPV is not a CSP partner with direct access to the Partner Center dashboard 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, download the Secure Application Model framework document. This document covers principles and best practices to make marketplace applications sustainable and robust from security compromises.

Samples

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

REST

To to make REST calls with the Secure Application Model framework with sample code, you must do the following:

  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

Tip

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

Note

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 at the following URL: https://login.microsoftonline.com/common/oauth2/authorize?client_id=Application-Id&response_mode=form_post&response_type=code%20id_token&scope=openid%20profile. 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
Cookie: OpenIdConnect.nonce.hOMjjrivcxzuI4YqAw4uYC%2F%2BILFk4%2FCx3kHTHP3lBvA%3D=dHVyRXdlbk9WVUZFdlFONVdiY01nNEpUc0JRR0RiYWFLTHhQYlRGNl9VeXJqNjdLTGV3cFpIWFg1YmpnWVdQUURtN0dvMkdHS2kzTm02NGdQS09veVNEbTZJMDk1TVVNYkczYmstQmlKUzFQaTBFMEdhNVJGVHlES2d3WGlCSlVlN1c2UE9sd2kzckNrVGN2RFNULWdHY2JET3RDQUxSaXRfLXZQdG00RnlUM0E1TUo1YWNKOWxvQXRwSkhRYklQbmZUV3d3eHVfNEpMUUthMFlQUFgzS01RS2NvMXYtbnV4UVJOYkl4TTN0cw%3D%3D

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.

Important

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:

resource=https%3a%2f%2fapi.partnercenter.microsoft.com&client_id=Application-Id&client_secret=Application-Secret&grant_type=authorization_code&code=AuthorizationCodeValue

Placeholder response:

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

Response body:

{"token_type":"Bearer","scope":"user_impersonation","expires_in":"3599","ext_expires_in":"3599","expires_on":"1547579127","not_before":"1547575227","resource":"https://api.partnercenter.microsoft.com","access_token”:”Access

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 token 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:

{"token_type":"Bearer","scope":"user_impersonation","expires_in":"3600","ext_expires_in":"3600","expires_on":"1547581389","not_before":"1547577489","resource":"https://api.partnercenter.microsoft.com","access_token":"AccessTokenValue","id_token":"IDTokenValue"}

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

PowerShell

The Partner Center PowerShell module is commonly used by partners to manage their Partner Center resources. It is an open source project maintained by the partner community. Since this module is maintained by the partner community, it is not officially supported by Microsoft. You can get help from the community or open an issue on GitHub if you encounter 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 PowerShell to add urn:ietf:wg:oauth:2.0:oob as a reply URL for your Azure AD application. Be sure to replace the value for the object identifier parameter with the object identifier for you Azure AD application. You can find this value in the Azure management portal.

    Connect-AzureAD
    
    Set-AzureADApplication -ObjectId 659dd68d-3414-4254-a48b-c081b5631b86 -ReplyUrls @("urn:ietf:wg:oauth:2.0:oob")
    
  3. Use the New-PartnerAccessToken command to perform the consent process and capture the required refresh token.

    $credential = Get-Credential
    
    $token = New-PartnerAccessToken -Consent -Credential $credential -Resource https://api.partnercenter.microsoft.com -ServicePrincipal
    

    Note

    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 require that a client identifier and secret be included in the access token request.

  4. Copy the refresh token value.

    $token.RefreshToken | clip
    
  5. When the Get-Credential command is invoked, you will be prompted to enter a username and password. Enter the application identifier as teh username. Enter the application secret as the password.

  6. 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 apppropriate permissions.

  7. After the New-PartnerAccessToken is successfully executed, the $token variable now contains the response from Azure AD. Be sure to note and store the refresh token value in a secure repository, such as Azure Key Vault.