Habilitar a estrutura do Modelo de Aplicativo SeguroEnabling the Secure Application Model framework

Aplica-se a:Applies to:

  • Partner CenterPartner Center

A Microsoft está introduzindo uma estrutura segura e escalonável para autenticar parceiros do CSP (Provedor de Soluções na Nuvem) e CPVs (Fornecedores de Painel de Controle) por meio da arquitetura da MFA (Autenticação Multifator) do 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.

Você pode usar o novo modelo para elevar a segurança para chamadas de integração da API do Partner Center.You can use the new model to elevate security for Partner Center API integration calls. Isso ajudará todas as partes (incluindo a Microsoft, os parceiros CSP e os CPVs) a protegerem a respectiva infraestrutura e os dados do cliente de riscos de segurança.This will help all parties (including Microsoft, CSP partners, and CPVs) to protect their infrastructure and customer data from security risks.

EscopoScope

Este artigo aborda os seguintes atores:This article concerns the following actors:

  • CPVsCPVs

    • Um CPV é um fornecedor independente de software que desenvolve aplicativos a serem usados por parceiros CSP para integração com as APIs do Partner Center.A CPV is an independent software vendor that develops apps for use by CSP partners to integrate with Partner Center APIs.
    • Um CPV não é um parceiro CSP com acesso direto às APIs ou ao painel do Partner Center.A CPV isn't a CSP partner with direct access to the Partner Center dashboard or APIs.
  • Provedores indiretos do CSP e parceiros CSP diretos que estão usando ID do aplicativo + autenticação de usuário e se integram diretamente às APIs do Partner Center.CSP indirect providers and CSP direct partners who are using app ID + user authentication and directly integrate with Partner Center APIs.

Requisitos de segurançaSecurity requirements

Para obter detalhes sobre os requisitos de segurança, confira Requisitos de Segurança do Parceiro.For details on security requirements, see Partner Security Requirements.

Modelo de Aplicativo SeguroSecure Application Model

Os aplicativos do Marketplace precisam representar os privilégios de parceiro CSP para poderem realizar chamadas às APIs da Microsoft.Marketplace applications need to impersonate CSP partner privileges to call Microsoft APIs. Ataques de segurança nesses aplicativos confidenciais podem levar ao comprometimento dos dados do cliente.Security attacks on these sensitive applications can lead to the compromise of customer data.

Para obter uma visão geral e detalhes da nova estrutura de autenticação, baixe o documento Estrutura do Modelo de Aplicativo Seguro.For an overview and details of the new authentication framework, download the Secure Application Model framework document. Esse documento aborda os princípios e as práticas recomendadas para tornar os aplicativos do Marketplace sustentáveis e robustos contra riscos de segurança.This document covers principles and best practices to make marketplace applications sustainable and robust from security compromises.

AmostrasSamples

Os documentos de visão geral e o código de exemplo a seguir descrevem como os parceiros podem implementar a estrutura do Modelo de Aplicativo Seguro:The following overview documents and sample code describe how partners can implement the Secure Application Model framework:

RESTREST

Para fazer chamadas REST com o código de exemplo da estrutura do Modelo de Aplicativo Seguro, siga estas etapas:To to make REST calls with the Secure Application Model framework with sample code, follow these steps:

  1. Criar um aplicativo WebCreate a web app

  2. Obter um código de autorizaçãoGet an authorization code

  3. Obter um token de atualizaçãoGet a refresh token

  4. Obter um token de acessoGet an access token

  5. Fazer uma chamada à API do Partner CenterMake a Partner Center API call

Dica

Você pode usar o módulo do PowerShell do Partner Center para obter um código de autorização e um token de atualização.You can use the Partner Center PowerShell module to get an authorization code and a refresh token. Você pode escolher essa opção no lugar das etapas 2 e 3.You can choose this option in place of steps 2 and 3. Para obter mais informações, confira os exemplos e a seção do PowerShell.For more information, see the PowerShell section and examples.

Criar um aplicativo WebCreate a web app

Você deve criar e registrar um aplicativo Web no Partner Center antes de fazer chamadas REST.You must create and register a web app in Partner Center before making REST calls.

  1. Entre no portal do Azure.Sign in to the Azure portal.

  2. Criar um aplicativo do Azure AD (Azure Active Directory).Create an Azure Active Directory (Azure AD) app.

  3. Conceda permissões de aplicativo delegadas aos recursos a seguir, dependendo dos requisitos do seu aplicativo.Give delegated application permissions to the following resources, depending on your application's requirements. Se necessário, você pode adicionar mais permissões delegadas para recursos do aplicativo.If necessary, you can add more delegated permissions for application resources.

    1. Microsoft Partner Center (alguns locatários mostram isso como SampleBECApp)Microsoft Partner Center (some tenants show this as SampleBECApp)

    2. APIs de Gerenciamento do Azure (se você estiver planejando chamar as APIs do Azure)Azure Management APIs (if you are planning to call Azure APIs)

    3. Microsoft Azure Active DirectoryWindows Azure Active Directory

  4. Verifique se a URL inicial do aplicativo está definida para um ponto de extremidade em que um aplicativo Web dinâmico está sendo executado.Make sure that the home URL of your app is set to an endpoint where a live web app is running. Esse aplicativo precisará aceitar o código de autorização da chamada de logon do Azure AD.This app will need to accept the authorization code from the Azure AD login call. Por exemplo, no código de exemplo na seção a seguir, o aplicativo Web está executando em https://localhost:44395/.For example, in the example code in the following section, the web app is running at https://localhost:44395/.

  5. Observe as seguintes informações das configurações do seu aplicativo Web no Azure AD:Note the following information from your web app's settings in Azure AD:

    • ID do aplicativoApplication ID
    • Segredo do aplicativoApplication secret

Observação

É recomendável usar um certificado como o segredo do aplicativo.It is recommended to use a certificate as your application secret. No entanto, você também pode criar uma chave de aplicativo no portal do Azure.However, you can also create an application key in the Azure portal. O código de exemplo na seção a seguir usa uma chave de aplicativo.The sample code in the following section uses an application key.

Obter código de autorizaçãoGet authorization code

Você deve obter um código de autorização para seu aplicativo Web aceitar da chamada de logon do Azure AD:You must get an authorization code for your web app to accept from the Azure AD login call:

  1. Faça logon no Azure AD pela seguinte 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. É necessário fazer logon com a conta de usuário da qual você fará chamadas à API do Partner Center (como uma conta de agente administrador ou agente de vendas).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. Substitua ID do aplicativo pela ID do aplicativo do Azure AD (GUID).Replace Application-Id with your Azure AD app ID (GUID).

  3. Quando solicitado, faça logon com sua conta de usuário com a MFA configurada.When prompted, log in with your user account with MFA configured.

  4. Quando solicitado, insira informações adicionais da MFA (número de telefone ou endereço de email) para verificar seu logon.When prompted, enter additional MFA information (phone number or email address) to verify your login.

  5. Depois que você estiver conectado, o navegador redirecionará a chamada para o ponto de extremidade do aplicativo Web com o seu código de autorização.After you are logged in, the browser will redirect the call to your web app endpoint with your authorization code. Por exemplo, o código de exemplo a seguir redireciona para https://localhost:44395/.For example, the following sample code redirects to https://localhost:44395/.

Rastreamento de chamada de código de autorizaçãoAuthorization 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>

Obter token de atualizaçãoGet refresh token

Em seguida, você precisa usar seu código de autorização para obter um token de atualização:You must then use your authorization code to get a refresh token:

  1. Faça uma chamada POST para o ponto de extremidade de logon do Azure AD https://login.microsoftonline.com/CSPTenantID/oauth2/token com o código de autorização.Make a POST call to the Azure AD login endpoint https://login.microsoftonline.com/CSPTenantID/oauth2/token with the authorization code. Para obter um exemplo, confira a chamada de exemplo a seguir.For an example, see the following sample call.

  2. Observe o token de atualização que é retornado.Note the refresh token that is returned.

  3. Armazene o token de atualização no Azure Key Vault.Store the refresh token in Azure Key Vault. Para obter mais informações, confira a documentação da API do Key Vault.For more information, see the Key Vault API documentation.

Importante

O token de atualização precisa estar armazenado como um segredo no Key Vault.The refresh token must be stored as a secret in Key Vault.

Chamada de atualização de exemploSample refresh call

Solicitação de espaço reservado: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

Corpo da solicitação:Request body:

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

Resposta de espaço reservado:Placeholder response:

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

Corpo da resposta: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

Obter token de acessoGet access token

Você precisa obter um token de acesso antes de poder fazer chamadas às APIs do Partner Center.You must obtain an access token before you can make calls to the Partner Center APIs. Você deve usar um token de atualização para obter um token de acesso porque o token de acesso geralmente tem um tempo de vida muito limitado (por exemplo, menos de uma hora).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).

Solicitação de espaço reservado: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

Corpo da solicitação: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

Resposta de espaço reservado:Placeholder response:

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

Corpo da resposta: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"}

Fazer chamadas à API do Partner CenterMake Partner Center API calls

Você deve usar seu token de acesso para fazer chamadas às APIs do Partner Center.You must use your access token to call the Partner Center APIs. Veja o exemplo de chamada a seguir.See the following example call.

Exemplo de chamada à API do Partner CenterExample 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

O módulo PowerShell do Partner Center é normalmente usado por parceiros para gerenciar os recursos do Partner Center.The Partner Center PowerShell module is commonly used by partners to manage their Partner Center resources. É um projeto de software livre mantido pela comunidade de parceiros.It's an open-source project maintained by the partner community. Esse módulo é mantido pela comunidade de parceiros e, por isso, não tem suporte oficial da Microsoft.Since this module is maintained by the partner community, it isn't officially supported by Microsoft. Caso se depare com um problema, você pode obter ajuda da comunidade ou abrir um problema no GitHub.You can get help from the community or open an issue on GitHub if you experience a problem.

Você pode usar o módulo do Partner Center PowerShell para reduzir a infraestrutura necessária para trocar um código de autorização para um token de acesso.You can use the Partner Center PowerShell module to reduce the required infrastructure to exchange an authorization code for an access token. Esse método é opcional para fazer chamadas REST do Partner Center.This method is optional for making Partner Center REST calls.

Para obter mais informações sobre esse processo, confira a documentação de Modelo de Aplicativo Seguro do PowerShell.For more information on this process, see Secure App Model PowerShell documentation.

  1. Instale os módulos do PowerShell do Partner Center e do Azure AD.Install the Azure AD and Partner Center PowerShell modules.

    Install-Module AzureAD
    
    Install-Module PartnerCenter
    
  2. Use o comando New-PartnerAccessToken para executar o processo de consentimento e capturar o token de atualização necessário.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
    

    Observação

    O parâmetro ServicePrincipal da entidade de segurança é usado com o comando New-PartnerAccessToken porque um aplicativo do Azure AD com um tipo Web/API está sendo usado.The ServicePrincipal parameter is used with the New-PartnerAccessToken command because an Azure AD app with a type of Web/API is being used. Esse tipo de aplicativo requer que um identificador de cliente e um segredo sejam incluídos na solicitação de token de acesso.This type of app requires that a client identifier and secret be included in the access token request. Quando o comando Get-Credential for invocado, você receberá uma solicitação para inserir um nome de usuário e uma senha.When the Get-Credential command is invoked, you will be prompted to enter a username and password. Insira o identificador do aplicativo como o nome de usuário.Enter the application identifier as the username. Insira o segredo do aplicativo como a senha.Enter the application secret as the password. Quando o comando New-PartnerAccessToken for invocado, você receberá uma solicitação para inserir as credenciais novamente.When the New-PartnerAccessToken command is invoked, you will be prompted to enter credentials again. Insira as credenciais para a conta de serviço que você está usando.Enter the credentials for the service account that you are using. Essa conta de serviço deve ser uma conta de parceiro com as permissões apropriadas.This service account should be a partner account with appropriate permissions.

  3. Copie o valor do token de atualização.Copy the refresh token value.

    $token.RefreshToken | clip
    

Você deve armazenar o valor do token de atualização em um repositório seguro, como o Azure Key Vault.You should store the refresh token value in a secure repository, such as Azure Key Vault. Para obter mais informações sobre como aproveitar o módulo de aplicativo seguro com o PowerShell, confira o artigo sobre autenticação multifator.For more information on how to leverage the secure application module with PowerShell, see the multi-factor authentication article.