Create a secure partner application

You can implement the Secure Application Model framework by creating an application for either Cloud Solution Providers (CSPs) or Control Panel Vendors (CPVs).

Implement secure application model

Steps to enable secure application model

Important

Azure Active Directory (Azure AD) Graph is deprecated as of June 30, 2023. Going forward, we're making no further investments in Azure AD Graph. Azure AD Graph APIs have no SLA or maintenance commitment beyond security-related fixes. Investments in new features and functionalities will only be made in Microsoft Graph.

We'll retire Azure AD Graph in incremental steps so that you have sufficient time to migrate your applications to Microsoft Graph APIs. At a later date that we will announce, we will block the creation of any new applications using Azure AD Graph.

To learn more, see Important: Azure AD Graph Retirement and Powershell Module Deprecation.

Create a Partner Center service principal

First, create a Microsoft Partner Center service principal in the CSP partner's tenant, where the multitenant application is going to be created.

For CSP partner tenants, this service principal should already exist. If not, create using the following steps.

In an administrator PowerShell window, run the following commands.

1. Install the AzureAD module. Install-Module Microsoft.Graph
2. Run Connect-MgGraph, this prompts for a user name and password. Enter the tenant admin credentials. Connect-MgGraph
3. Create a Microsoft Partner Center service principal. New-MgServicePrincipal -DisplayName "Microsoft Partner Center" -AppId fa3d9a0c-3fb0-42cc-9193-47c7ecd2edbd

Create a multitenant application in the CSP partner's tenant

Use the following steps to make sure that the following application properties are set for the newly created multitenant application.

1. Sign in into portal.azure.com
2. Select Microsoft Entra ID and App registrations to create new registrations with multitenant.

3. Select a user-facing display name for your application.
4. Select Supported account type: Accounts in any organizational directory (Any Microsoft Entra directory - Multitenant).
5. Select a platform type "Web."
6. The Redirect URL must be your application redirect URL, which will show the consent success message to the partner and collect a refresh token. Make sure that the redirect URL of your app is set to an endpoint where a live web app is running. This app needs to accept the authorization code from the Microsoft Entra sign-in call.
7. Go to Manage > Certificates & secrets > +New client secret in the Client secrets tab.

Note

You'll need the following information from your web app's settings in Microsoft Entra ID:

• Application ID
• Application secret

Apply permissions

Make sure the following permissions are set for the multitenant application.

In the API permission section:

• There shouldn't be any direct Application Permissions to the multitenant application.

• Follow the below path for adding Delegated permissions for Microsoft Graph:

  • API Permissions > Add a permission > Microsoft APIs > Microsoft Graph > Delegated Permissions
    • DelegatedAdminRelationship.ReadWrite.All User.Read.All

  

  • Follow the below path for adding Delegated permissions for Microsoft Partner Center - Grant Access Partner Center permissions under Delegated Permissions:
    • API Permissions > Add a permission > APIs my organization uses > Microsoft Partner Center > Delegated Permissions > User Impersonation

  

Provide consent link

Present the partner with the consent link and have them sign in with their service account to approve the application to act on behalf of the service account on the partner tenant.

The CSP partner user must be a Global Admin and an Admin Agent to consent the multitenant application.

Multi tenant application

The multi tenant ApplicationID needs to be replaced with your Application ID.

Navigate to App Registrations and select the Application (Client) ID and replace below.

Get authorization code

You must get an authorization code for your web app from the Microsoft Entra sign-in call:

1. Sign in to Microsoft Entra ID.
2. Replace Application-Id with your Microsoft Entra app ID (GUID).
3. When prompted, sign in with your user account with MFA configured.
4. When prompted, enter other MFA information (phone number or email address) to verify your sign-in.
5. After you're 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/.

GET https://login.microsoftonline.com/common/oauth2/authorize?&client_id=<CSPApplicationId>&response_type=code&redirect_url=https://<CSPApplicationUrl_which_collects_refreshtoken>

or

GET https://login.microsoftonline.com/common/oauth2/authorize?&client_id=<CSPApplicationId>&response_type=code

For China, use the following link:

GET https://login.chinacloudapi.cn/common/oauth2/authorize ?&client_id= <CSPApplicationId>&response_type=code&redirect_url= https://<CSPApplicationUrl_which_collects_refreshtoken>

or

GET https://login.chinacloudapi.cn/common/oauth2/authorize?&client_id= <CSPApplicationId>&response_type=code

Authorization code call trace: https://localhost:44395/?code=<authorization_code>&<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 Microsoft Entra sign-in 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 the Azure Key Vault. For more information, see the Key Vault API documentation.

Note

The resources mentioned in the below sample POST call are for GDAP-Graph APIs.

Resources for other PC APIs are as follows:

Partner Center APIs (https://api.partnercenter.microsoft.com)

GDAP APIs

Partner API (https://api.partner.microsoft.com)

Sample call

POST  'https://login.microsoftonline.com/<partnerTenantId>/oauth2/token' \
--header 'content-type: application/x-www-form-urlencoded' \
--form 'grant_type="authorization_code"' \
--form 'client_id=<application_id or client_id>' \
--form 'resource="https://graph.microsoft.com"' \
--form 'code="<authorization_code>"'   
Response Body:

{
    "token_type": "Bearer",
    "scope": "DelegatedAdminRelationship.ReadWrite.All User.Read.All",
    "expires_in": "4549",
    "ext_expires_in": "4549",
    "expires_on": "1652886571",
    "not_before": "1652881721",
    "resource": "https://graph.microsoft.com",
    "access_token": "Access_token",
    "refresh_token": "Refresh_token",    
    "id_token": "Id_token"
}

Set up key vault

First, create a new web application in the CSP partner's tenant. If the CPV application is used for calling the Partner Center APIs, CPV should create a new web application in the CPV partner's tenant.

If you're using Azure Key Vault:

1. Create the Azure Key Vault with the appropriate <key-vault-name> and it results in a DNS name like: https://<key-vault-name>.vault.azure.net
2. Add a refresh token to the key vault.

Provide access to the key vault

In the access policies of the key vault, add the KeyVaultAccessApp with permissions to only manage the Get and Set aspects of a Secret.

Configure the prototype

The prototype has two applications:

• Partner Consent: Represents a web application designed to accept consent from a CSP partner and show a success message.
  • This application sets up consent and captures the refresh token of the consented user.
  • The consented user's refresh token is used for generating the access token for the CSP partner tenant.
• CSP application or CPV application: Represents a primary application, which calls Partner Center APIs and graph.
  • APIs to perform commerce and user actions on behalf of the partner.

This application retrieves the access token for a specific audience (Partner Center APIs or Graph) before calling respective APIs. It uses the refresh token that is stored securely in the key vault.

Partner consent application (CSP)

CSP web configuration

For the CSP partner application, the web.config file has the following sections called out. Update these values with corresponding application IDs and secrets. For your primary application, use "certificate" as the web application secret instead of plain secrets because it provides an extra layer of security.

<!-- AppID that represents CSP application -->
<add key="ida:CSPApplicationId" value="CSPApplicationIdValue" />
<!--
Please use certificate as your client secret and deploy the certificate to your environment.
The following application secret is for sample application only. please do not use secret directly from the config file.
-->
<add key="ida:CSPApplicationSecret" value="CSPApplicationSecretValue" />
<!-- AppID that is given access for keyvault to store the refresh tokens --> <add key="ida:KeyVaultClientId" value="KeyVaultClientIdValue" />
<!--
Please use certificate as your client secret and deploy the certificate to your environment.
The following application secret is for sample application only. please do not use secret directly from the config file.
-->
<add key="ida:KeyVaultClientSecret" value="KeyVaultClientSecretValue" />
<!-- AAD instance: Global is .com, for different national clouds it changes German cloud: .de, China cloud: login.chinacloudapi.cn -->
<add key="ida:AADInstance" value="https://login.microsoftonline.com/" />

CSP application configuration

For the CSP partner application, the app.config file has the following sections called out. Update the values with the corresponding application IDs and secrets. For your primary application, use "certificate" as the web application secret instead of plain secrets because it provides an extra layer of security.

<!-- AppID that represents CSP application -->
<add key="ida:CPVApplicationId" value="CPVApplicationIdValue" />
<!--
Please use certificate as your client secret and deploy the certificate to your environment. The following application secret is for sample application only. please do not use secret directly from the config file.
-->
<add key="ida:CPVApplicationSecret" value="CPVApplicationSecretValue" />
<!-- AppID that is given access for keyvault to store the refresh tokens -->
<add key="ida:KeyVaultClientId" value="KeyVaultClientIdValue" />
<!--
Please use certificate as your client secret and deploy the certificate to your environment. The following application secret is for sample application only. please do not use secret directly from the config file.
-->
<add key="ida:KeyVaultClientSecret" value="KeyVaultClientSecretValue" />
<!-- AAD instance: Global is .com, for different national clouds it changes German cloud: .de,
China cloud: login.chinacloudapi.cn -->
<add key="ida:AADInstance" value="https://login.microsoftonline.com/" />

Partner consent application (CPV)

CSPs using the CPV application can call the ApplicationConsent API to create the service principal on the customer tenant to access the Microsoft Graph to manage the customer tenants. For more information, see Partner Center authentication.

CPV web configuration

For the CSP partner application, the web.config file has the following sections called out. Update these values with corresponding application IDs and secrets. For your primary application, use "certificate" as the web application secret instead of plain secrets because it provides an extra layer of security.

<!-- AppID that represents Control panel vendor application -->
<add key="ida:CPVApplicationId" value="CPVApplicationIdValue" />
<!--
Please use certificate as your client secret and deploy the certificate to your environment. The following application secret is for sample application only. please do not use secret directly from the config file.
-->
<add key="ida:CPVApplicationSecret" value="CPVApplicationSecretValue" />
<!-- AppID that is given access for keyvault to store the refresh tokens -->
<add key="ida:KeyVaultClientId" value="KeyVaultClientIdValue" />
<!--
Please use certificate as your client secret and deploy the certificate to your environment. The following application secret is for sample application only. please do not use secret directly from the config file.
-->
<add key="ida:KeyVaultClientSecret" value="KeyVaultClientSecretValue" />
<!-- AAD instance: Global is .com, for different national clouds it changes German cloud: .de, China cloud: login.chinacloudapi.cn -->
<add key="ida:AADInstance" value="https://login.microsoftonline.com/" />

CPV application configuration

For the CPV partner application, the app.config file has the following sections called out. Update the values with the corresponding application IDs and secrets. For your primary application, use "certificate" as the web application secret instead of plain secrets because it provides an extra layer of security.

<!-- AppID that represents Control panel vendor application -->
<add key="ida:CPVApplicationId" value="CPVApplicationIdValue" />
<!--
Please use certificate as your client secret and deploy the certificate to your environment. The following application secret is for sample application only. please do not use secret directly from the config file.
-->
<add key="ida:CPVApplicationSecret" value="CPVApplicationSecretValue" />
<!-- AppID that is given access for keyvault to store the refresh tokens -->
<add key="ida:KeyVaultClientId" value="KeyVaultClientIdValue" />
<!--
Please use certificate as your client secret and deploy the certificate to your environment. The following application secret is for sample application only. please do not use secret directly from the config file.
-->
<add key="ida:KeyVaultClientSecret" value="KeyVaultClientSecretValue" />
<!-- AAD instance: Global is .com, for different national clouds it changes German cloud: .de, China cloud: login.chinacloudapi.cn -->
<add key="ida:AADInstance" value="https://login.microsoftonline.com/" />