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 multifactor authentication (MFA) architecture. CSP partners and Control Panel Vendors can rely on the new model to elevate security for Partner Center API integration calls. This helps all parties including Microsoft, CSP partners and Control Panel Vendors to protect their infrastructure and customer data from security risks.
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.
Scope
This article applies to the following partners:
- Control Panel Vendors (CPVs) are independent software vendors who develop apps for use by CSP partners to integrate with Partner Center APIs. A CPV isn't a CSP partner with direct access to the partner dashboard or APIs. They're the companies that develop applications (usually web apps) that enable CSPs to sell their products through a unified marketplace.
- CSP indirect providers and CSP direct partners who are using app ID + user authentication and directly integrate with Partner Center APIs.
Note
To qualify as a CPV, you must onboard to Partner Center as a CPV first. If you are an existing CSP partner who is also a CPV, this prerequisite applies to you, as well.
Secure application development
In the process of placing orders for Microsoft products on behalf of CSPs, marketplace applications from CPVs interact with Microsoft APIs to place orders and provision resources for customers.
Some of these APIs include:
- Partner Center APIs implementing commerce operations like placing orders and managing subscription lifecycles.
- Microsoft Graph APIs that implement identity management for CSP tenants and CSP customer's tenants.
- Azure Resource Manager (ARM) APIs implementing Azure deployment functionality.
CSP partners are empowered with delegated privileges to act on behalf of their customers when calling Microsoft APIs. Delegated privileges allow CSP partners to complete purchase, deployment, and support scenarios for their customers.
Marketplace applications are designed to help CSP partners list their solutions for customers. To achieve this, marketplace applications need to impersonate CSP partner privileges to call Microsoft APIs.
Since CSP partner privileges are high and provide access to all of the partner's customers, it's important to understand how these applications must be designed to withstand security exploitation vectors. Security attacks on these sensitive applications can lead to the compromise of customer data. Therefore, permission grants and partner privilege impersonation must be designed to follow the principle of least privilege. The following principles and best practices ensure that marketplace applications are sustainable and can withstand compromises.
Security principles for credentials impersonation
Marketplace applications must not store any credentials from CSP partners.
CSP partner user passwords shouldn't be shared.
CSP partner tenant web app keys must not be shared with Control Panel Vendors.
A marketplace application must present the application identity along with partner information as opposed to using only partner credentials when making calls impersonating a CSP partner identity.
Access to a marketplace application must be based on the principle of least privilege and clearly articulated in permissions.
Authorization for a marketplace application must be pivoted to multiple credentials.
Application credentials and partner credentials must be provided together to gain access.
Important
It is important that there is no single point of compromise.
Access must be restricted to a specific audience or API.
Access must identify the purpose of the impersonation.
Access permissions for a marketplace application must be time bound. CSP partners must be able to renew or revoke access to the marketplace application.
Quick control or remediation processes must be in place to handle compromises of marketplace application credentials.
All user accounts should use two-factor authentication (2FA).
The application model should be friendly to extra security provisions, like conditional access to a better security model.
Note
CSP indirect providers and CSP direct partners who are using app ID + user authentication and directly integrate with Partner Center APIs are required to follow the above principles to secure their own marketplace applications.
Application identity and concepts
Multitenant applications
A multitenant application is generally a software as a service (SaaS) application. You can configure your application to accept sign-ins from any Microsoft Entra tenants by configuring the application type as multitenant on the Azure dashboard. Users in any Microsoft Entra tenant will be able to sign in to your application after consenting to use their account with your application.
To learn more about creating a multitenant application, see Sign in any Microsoft Entra user using the multitenant application pattern.
Consent framework
For a user to sign in to an application in Microsoft Entra ID, the application must be represented in the user's tenant, which allows the organization to do things like apply unique policies when users from their tenant sign-in to the application. For a single tenant application, this registration is simple: it's the one that happens when you register the application in the Azure dashboard.
For a multitenant application, the initial registration for the application lives in the Microsoft Entra tenant used by the developer. When a user from a different tenant signs in to the application for the first time, Microsoft Entra ID asks them to consent to the permissions requested by the application. If they consent, then a representation of the application called a service principal is created in the user's tenant, and the sign in process can continue. A delegation is also created in the directory that records the user's consent to the application.
Note
CSP indirect providers and CSP direct partners who are using app ID + user authentication and directly integrate with Partner Center APIs will have to give consent to their marketplace application using the same consent framework.
The consent experience is affected by the permissions requested by the application. Microsoft Entra ID supports two kinds of permissions, app-only and delegated.
- App-only permission is granted directly to the identity of the application. For example, you can grant an application permission to read the list of users in a tenant, regardless of who is signed in to the application.
- Delegated permission grants an application the ability to act as a signed in user for a subset of the things the user can do. For example, you can grant an application the delegated permission to read the signed in user's calendar.
Some permissions are consented to by a regular user, while others require a tenant administrator's consent. For more information on Microsoft Entra consent framework, see Understanding Microsoft Entra application consent experiences.
- Scopes, permissions, and consent in the Azure Active Directory v2.0 endpoint
- Understanding user and admin consent
Multitenant application open authorization (OAuth) token flow
In a multitenant application open authorization (OAuth) flow, the application is represented as a multitenant application in the CPV or CSP partner's tenant.
To access Microsoft APIs (Partner Center APIs, Graph APIs, and so on), CSP partners must log in to the application and consent to allow the application to call APIs on their behalf.
Note
CSP indirect providers and CSP direct partners who are using app ID and user authentication and directly integrate with Partner Center APIs will have to give consent to their marketplace application to use the same consent framework.
The application gains access to the partner's resources, like Graph and Partner Center APIs, through consent and OAuth grants.
Create a multitenant application
A multitenant application must adhere to the following requirements:
- It must be a web app with an application ID and secret key.
- It must have implicit authentication mode turned off.
In addition, we recommend adhering to these best practices:
- Use a certificate for the secret key.
- Enable conditional access to apply IP range restrictions. This might require more functionality to be enabled on the Microsoft Entra tenant.
- Apply access token lifetime policies for the application.
When acquiring a token, the app ID and secret key must be presented. The secret key can be a certificate.
The application can be configured to call multiple APIs including Azure Resource Manager APIs. The following are the minimum set of permissions required for Partner Center APIs:
- Microsoft Entra ID delegated permissions: Access the directory as signed in user
- Partner Center APIs delegated permissions: Access
Application captures partner consent
A multitenant application must acquire consent from partners and use the consent and grant to make further calls to Partner Center APIs. Consent is acquired through an OAuth authentication code flow.
To acquire consent, CPVs or CSP partners must build an onboarding website that can accept an authentication code grant from Microsoft Entra ID.
For more information, see Authorize access to Azure Active and Directory web applications using the OAuth 2.0 code grant flow.
Here are the steps for a multitenant application to capture CSP partner consent along with a reusable token for making calls to Partner Center APIs.
Use the following steps to acquire partner consent.
- Build a partner onboarding web application that can host a consent link for the partner to click through to accept consent for the multitenant application.
- The CSP partner clicks on the consent link. For example,
https://login.microsoftonline.com/common/oauth2/authorize?&client_id=<marketplaceappid>&response_ty - The Microsoft Entra login page explains the permissions that will be granted to the application on behalf of the user. The CSP partner can decide to use either Admin Agent or Sales Agent credentials to sign in and approve the consent. The application is given permissions based on the user role used to sign in.
- Once consent is granted, Microsoft Entra ID creates a service principal of the CPV's multitenant application into the CSP partner's tenant. The application is given OAuth grants to act on behalf of the user. These grants allow the multitenant application to call Partner Center APIs on behalf of the partner. At this point, the Microsoft Entra login page redirects to the partner onboarding web application. The web application receives an authorization code from Microsoft Entra ID. The partner onboarding web application must use the authorization code along with the application ID and secret key to call the Microsoft Entra ID Tokens API to obtain a refresh token.
- Securely store the refresh token. The refresh token is part of the partner credentials used to obtain access to Partner Center APIs on behalf of the partner. Once the refresh token is acquired, encrypt it and store it in a secret key store, such as the Azure key vault.
Token request call flow
A CPVs or CSP partner's application must acquire an access token before making calls to Partner Center APIs. These APIs are represented at resource URL https://api.partnercenter.microsoft.com.
A CPV application should identify which partner account it must impersonate to call Partner Center APIs based on either product or federated sign-in. The application retrieves the encrypted refresh token for that partner tenant from the secret key store. The refresh token must be decrypted before use.
For CSP partners where there's only one tenant who gives consent, the partner account refers to the CSP partner's tenant.
The refresh token is a multi-audience token. That means the refresh token can be used to obtain a token for multiple audiences based on the consent that is granted. For example, if partner consent is given for Partner Center APIs and Microsoft Graph APIs, the refresh token can be used to request an access token for both APIs. The access token has the "on behalf of" grant and allows a marketplace application to impersonate the partner who consented while calling these APIs.
An access token can be acquired for a single audience at a time. If an application needs to access multiple APIs, it must request multiple access tokens for the targeted audience. To request an access token, the application needs to call the Microsoft Entra ID Tokens API. Alternatively, it could also use the Microsoft Entra SDK's AuthenticationContext.AcquireTokenAsync and pass in following information:
- Resource URL, which is the endpoint URL for the application to be called. For example, the resource URL for the Microsoft Partner Center API is
https://api.partnercenter.microsoft.com. - Application credentials consisting of the web app's application ID and secret key.
- The refresh token
The resulting access token allows the application to make calls to APIs that are mentioned in the resource. The application can't request an access token for APIs that weren't granted permission as part of the consent request. The UserPrincipalName (UPN) attribute value is the Microsoft Entra username for the user accounts.
More considerations
Conditional access
When it comes to managing your cloud resources, a key aspect of cloud security is identity and access. In a mobile-first, cloud-first world, users can access your organization's resources using various devices and apps from anywhere. Simply focusing on who can access a resource is no longer enough. To master the balance between security and productivity, you also need to consider how a resource is accessed. By using Microsoft Entra Conditional Access, you can address this requirement. With conditional access, you can implement automated access control decisions for accessing your cloud apps that are based on conditions.
For more information, see What is conditional access in Microsoft Entra ID?
IP range-based restrictions
You can restrict tokens to be issued to specific range of IP addresses only. This feature helps restrict the surface area of attack to a specific network only.
Multifactor authentication
Enforcing multifactor authentication helps restrict credential compromise situations by enforcing credentials verification to two or more forms. This feature allows Microsoft Entra ID to validate the identity of the caller via secure secondary channels, such as mobile or email, before issuing tokens.
For more information, see How it works: Azure Multi.