Включение платформы "Модель безопасных приложений".Enabling the Secure Application Model framework

Относится кApplies to:

  • Центр партнеровPartner Center

Корпорация Майкрософт представляет безопасную масштабируемую платформу проверки подлинности для партнеров в рамках программы "Поставщик облачных решений" (CSP) и поставщиков панели управления (CPV), использующих архитектуру многофакторной проверки подлинности (MFA) Microsoft Azure.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.

Нова модель позволяет повысить уровень безопасности вызовов интеграции к API Центра партнеров.You can use the new model to elevate security for Partner Center API integration calls. Это поможет всем сторонам (корпорации Microsoft, партнерам CSP и CPV) защищать свои инфраструктуры и данные клиентов от угроз безопасности.This will help all parties (including Microsoft, CSP partners, and CPVs) to protect their infrastructure and customer data from security risks.

ОбластьScope

Эта статья затрагивает следующие стороны:This article concerns the following actors:

  • Поставщики CPV:CPVs

    • CPV — это независимый поставщик программного обеспечения, разрабатывающий приложения для интеграции с интерфейсами API Центра партнеров, которые будут использовать партнеры в рамках CSP.A CPV is an independent software vendor that develops apps for use by CSP partners to integrate with Partner Center APIs.
    • CPV не является партнером в рамках CSP и не имеет прямого доступа к Панели мониторинга или API Центра партнеров.A CPV isn't a CSP partner with direct access to the Partner Center dashboard or APIs.
  • Косвенные поставщики и прямые партнеры в рамках CSP, которые используют проверку подлинности по идентификатору приложения и пользователю, а также напрямую интегрируются с APII-интерфейсами Центра партнеров.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 должны олицетворять привилегии партнеров CSP при вызове интерфейсов API корпорации Майкрософт.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. В этом документе описаны принципы и приведены рекомендации, позволяющие сделать приложения marketplace устойчивыми и надежно защищенными от угроз безопасности.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:

RESTREST

Чтобы создавать вызовы REST с помощью примера кода для платформы Модели безопасных приложений, выполните следующие действия: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. Вызов к API Центра партнеров.Make a Partner Center API call

Совет

Получить код авторизации и маркер обновления можно с помощью модуля PowerShell для Центра партнеров.You can use the Partner Center PowerShell module to get an authorization code and a refresh token. Этот вариант заменит приведенные здесь шаги 2 и 3.You can choose this option in place of steps 2 and 3. См. в раздел со сведениями и примерами для PowerShell.For more information, see the PowerShell section and examples.

Создание веб-приложенияCreate a web app

Прежде чем создавать вызовы REST, необходимо создать веб-приложение и зарегистрировать его в Центре партнеров.You must create and register a web app in Partner Center before making REST calls.

  1. Войдите на портал Azure.Sign in to the Azure portal.

  2. Создайте приложение Azure Active Directory (AAD).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. Центр партнеров (Майкрософт) , который в некоторых клиентах отображается как SampleBECApp.Microsoft Partner Center (some tenants show this as SampleBECApp)

    2. API управления Azure, если вы намерены обращаться к API Azure.Azure Management APIs (if you are planning to call Azure APIs)

    3. Windows Azure Active Directory.Windows Azure Active Directory

  4. Убедитесь, что URL-адрес главной страницы приложения указывает на правильную конечную точку, где работает веб-приложение.Make sure that the home URL of your app is set to an endpoint where a live web app is running. Это приложение должно принимать код авторизации из вызова для входа в AAD.This app will need to accept the authorization code from the Azure AD login call. Например, в коде из следующего раздела веб-приложение работает в конечной точке https://localhost:44395/.For example, in the example code in the following section, the web app is running at https://localhost:44395/.

  5. Обратите внимание на следующие сведения, указанные для веб-приложения в AAD:Note the following information from your web app's settings in Azure AD:

    • Application IDApplication ID
    • секрет приложения.Application secret

Примечание

Мы рекомендуем использовать сертификат безопасности в качестве секрета приложения.It is recommended to use a certificate as your application secret. Но вместо этого вы можете создать ключ приложение на портале Azure.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

Вам необходимо получить код авторизации из вызова для входа в AAD, чтобы приложение приняло такой код.You must get an authorization code for your web app to accept from the Azure AD login call:

  1. Войдите в Azure AD по следующему URL-адресу: https://login.microsoftonline.com/common/oauth2/authorize?client_id=Application-Id&response_mode=form_post&response_type=code%20id_token&scope=openid%20profile&nonce=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&nonce=1. Не забудьте, что для входа нужно использовать именно ту учетную запись пользователя, с которой вы будете выполнять вызовы к API Центра партнеров (например, агента по администрированию или агента по продажам).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. Замените заполнитель Application-Id реальным идентификатором приложения AAD (GUID).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. Например, в следующем примере кода перенаправление выполняется на адрес https://localhost:44395/.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. Выполните вызов POST к конечной точке входа в AAD (https://login.microsoftonline.com/CSPTenantID/oauth2/token) с этим кодом авторизации.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. Сохраните маркер обновления в Azure Key Vault.Store the refresh token in Azure Key Vault. Дополнительные сведения см. в документации по API Key Vault.For more information, see the Key Vault API documentation.

Важно!

Этот маркер обновления следует сохранить как секрет в Key Vault.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

Вам необходимо получить маркер доступа, прежде чем выполнять вызовы к API Центра партнеров.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"}

Выполнение вызовов к API Центра партнеровMake Partner Center API calls

При обращении к API Центра партнеров вам следует использовать маркер доступа.You must use your access token to call the Partner Center APIs. Пример приводится ниже.See the following example call.

Пример вызова к API Центра партнеров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

PowerShellPowerShell

Модуль PowerShell Центра партнеров часто используется партнерами для управления ресурсами Центра партнеров.The Partner Center PowerShell module is commonly used by partners to manage their Partner Center resources. Это проект с открытым кодом, поддерживаемый сообществом партнеров.It's an open-source project maintained by the partner community. Так как этот модуль поддерживается сообществом партнеров, он официально не поддерживается корпорацией Майкрософт.Since this module is maintained by the partner community, it isn't officially supported by Microsoft. При необходимости вы можете получить помощь от сообщества или опубликовать проблему в GitHub.You can get help from the community or open an issue on GitHub if you experience a problem.

С помощью модуля PowerShell для Центра партнеров вы можете уменьшить строгость требований к инфраструктуре для обмена кода авторизации на код доступа.You can use the Partner Center PowerShell module to reduce the required infrastructure to exchange an authorization code for an access token. Это альтернативный метод для выполнения вызовов к REST API Центра партнеров.This method is optional for making Partner Center REST calls.

Дополнительные сведения об этом процессе см. в этой статье в документации по PowerShell.For more information on this process, see Secure App Model PowerShell documentation.

  1. Установка модулей PowerShell для AAD и Центра партнеров.Install the Azure AD and Partner Center PowerShell modules.

    Install-Module AzureAD
    
    Install-Module PartnerCenter
    
  2. С помощью команды New-PartnerAccessToken подтвердите согласие и получите необходимый маркер обновления.Use the New-PartnerAccessToken command to perform the consent process and capture the required refresh token.

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

    Примечание

    В новой команде New-PartnerAccessToken указывается параметр ServicePrincipal, так как используемое приложение AAD имеет тип Web/API.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. При вызове команды Get-Credential вам будет предложено ввести имя пользователя и пароль.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. При вызове команды New-PartnerAccessToken вам будет предложено снова ввести учетные данные.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
    

Маркер обновления нужно хранить в защищенном репозитории, например в Azure Key Vault.You should store the refresh token value in a secure repository, such as Azure Key Vault. Дополнительные сведения о работе с модулем защищенных приложений в PowerShell см. в статье Многофакторная проверка подлинности.For more information on how to leverage the secure application module with PowerShell, see the multi-factor authentication article.