Como delegar o registro de usuário e a assinatura do produto

APPLIES TO: Desenvolvedor | Básico | Básico v2 | Padrão | Standard v2 | Premium | Premium v2

A delegação permite que seu site possua os dados do usuário e execute a validação personalizada para os usuários do portal do desenvolvedor. Com a delegação, você pode lidar com a entrada e a inscrição do desenvolvedor (e operações de gerenciamento de conta relacionadas) e a assinatura do produto usando seu site existente, em vez da funcionalidade interna do portal do desenvolvedor.

Delegar entrada e inscrição de desenvolvedores

Para delegar a entrada e a inscrição do desenvolvedor no seu site existente, crie um ponto de extremidade de delegação especial no seu site. Essa delegação especial atua como ponto de entrada para qualquer solicitação de login/registro e outras relacionadas, iniciadas no portal do desenvolvedor do API Management.

O fluxo de trabalho final consiste nestas etapas:

1. O desenvolvedor clica no link de login ou de inscrição ou em um link de gerenciamento de conta no portal do desenvolvedor do Gerenciamento de API.
2. O navegador redireciona para o ponto de extremidade da delegação.
3. O ponto de extremidade de delegação no retorno redireciona o usuário ou apresenta a interface do usuário de entrada/inscrição ou gerenciamento de conta.
4. Após a conclusão da operação, o usuário é redirecionado de volta ao portal do desenvolvedor do Gerenciamento de API no local de onde saiu.

Configurar o Gerenciamento de API para rotear solicitações por meio do ponto de extremidade de delegação

1. No portal do Azure, acesse sua instância de Gerenciamento de API.

2. No menu da barra lateral, no portal do Desenvolvedor, selecione Delegação.

3. Marque a caixa de seleção para ativar a delegação.

4. Selecione caixa de seleção para habilitar a opção Delegar entrada e inscrição.

   

5. Escolha a URL do ponto de extremidade especial de delegação e insira-a no campo Ponto de extremidade do serviço de delegação.

6. Em Chaves de delegação:

   • Gere a chave de validação primária ou a chave de validação secundária (ou ambas) a serem usadas pelo serviço de delegação para validar solicitações do Gerenciamento de API. Selecione as reticências (...) ao lado de qualquer chave e selecione Regenerar.
   • Selecione as reticências (...) ao lado de qualquer chave e selecione Copiar. Copie as chaves para um local seguro e use-as ao configurar o serviço de delegação.

7. Clique em Salvar.

Criar seu ponto de extremidade de delegação

Para criar um novo ponto de extremidade de delegação a ser implementado em seu site, siga estas etapas:

1. Receba uma solicitação no seguinte formulário, dependendo da operação:

   http://www.yourwebsite.com/apimdelegation?operation={operation}& returnUrl={URL da página de origem}&salt={string}&sig={string}

   -Ou-

   http://www.yourwebsite.com/apimdelegation?operation={operation}& userId={ID de usuário da conta}&salt={string}&sig={string}

   Parâmetros de consulta:

   Parâmetro	Descrição
   operation	Identifica o tipo de solicitação de delegação. Operações disponíveis: SignIn, SignUp, ChangePassword, ChangeProfile, CloseAccount, SignOut.
   returnUrl	Em SignIn ou SignUp, a URL de onde o usuário clicou em um link de entrada ou de inscrição.
   userId	Em ChangePassword, ChangeProfile, CloseAccount e SignOut, a ID de usuário da conta que você quer gerenciar.
   salt	Uma cadeia salt especial utilizada para calcular um hash de segurança.
   sig	Um hash de segurança calculado para ser utilizado na comparação com o seu próprio hash calculado.

2. Confirme que a solicitação está vindo do Gerenciamento de API do Azure (opcional, mas altamente recomendado por segurança).

   • Calcule um hash HMAC-SHA512 de uma cadeia de caracteres baseada nos parâmetros de consulta returnUrl (ou UserId) e salt. Para obter mais detalhes, consulte nosso exemplo de código.

     Para SignIn e SignUp:

     HMAC(salt + '\n' + returnUrl)
     

     Para ChangePassword, ChangeProfile, CloseAccount e SignOut:

     HMAC(salt + '\n' + userId)
     

   • Compare o hash calculado acima ao valor do parâmetro de consulta sig. Se os dois hashes forem correspondentes, prossiga para a próxima etapa. Caso contrário, recuse a solicitação.

3. Verifique se você recebeu uma solicitação de uma operação de entrada/inscrição ou gerenciamento de conta.

4. Apresente ao usuário a interface do usuário de entrada/inscrição ou gerenciamento de conta.

5. Depois de concluir a operação do seu lado, gerencie o usuário em Gerenciamento de API. Por exemplo, se o usuário se inscrever, crie uma conta correspondente para ele no Gerenciamento de API.

   • Crie um usuário com a API REST do Gerenciamento de API.
   • Defina a ID de usuário como o mesmo valor no seu armazenamento de usuários ou uma nova ID que seja fácil de rastrear.

6. Após a entrada ou inscrição, quando o usuário é autenticado com êxito:

   • Solicite um token de acesso compartilhado por meio da API REST do Gerenciamento de API.

   • Anexe um parâmetro de consulta returnUrl ao URL SSO que você recebeu da chamada à API acima. Por exemplo:

     https://contoso.developer.azure-api.net/signin-sso?token=<URL-encoded token>&returnUrl=%2Freturn%2Furl

   • Redirecionar o usuário para a URL produzida acima.

Delegação da assinatura de produtos

A delegação de assinaturas de produto funciona de forma semelhante à delegação de uma entrada/inscrição de usuário. O fluxo de trabalho final consiste nestas etapas:

1. O desenvolvedor seleciona um produto no portal do desenvolvedor do Gerenciamento de API e seleciona o botão Assinar .
2. O navegador redireciona para o ponto de extremidade da delegação.
3. O ponto de extremidade de delegação executa as etapas necessárias da assinatura do produto, que você cria. Estas etapas podem incluir:
   • Redirecionar para outra página a fim de solicitar informações de cobrança.
   • Fazendo mais perguntas.
   • Armazenar as informações e não exigir nenhuma ação do usuário.

Habilitar a funcionalidade do Gerenciamento de API

Na página Delegação , selecione a caixa de seleção para habilitar a delegação e habilite a assinatura delegada do produto.

Criar seu ponto de extremidade de delegação

Para criar um novo endpoint de delegação para seu site, siga estas etapas:

1. Receber uma solicitação no seguinte formulário, dependendo da operação.

   http://www.yourwebsite.com/apimdelegation?operation={operation}&productId={product to subscribe to}&userId={user making request}&salt={string}&sig={string}

   -Ou-

   http://www.yourwebsite.com/apimdelegation?operation={operation}&subscriptionId={subscription to manage}&salt={string}&sig={string}

   Parâmetros de consulta:

   Parâmetro	Descrição
   operation	Identifica o tipo de solicitação de delegação. As opções válidas de solicitação de assinatura de produto são: Assinar: uma solicitação para que o usuário assine determinado produto com uma ID fornecida (veja abaixo). Cancelar assinatura: uma solicitação para cancelar a assinatura de um usuário de um produto
   Productid	Em Assinar, a ID do produto para o qual o usuário solicitou a assinatura.
   userId	Em Assinar, a ID do usuário solicitante.
   subscriptionId	Em Cancelar assinatura, a ID da assinatura do produto.
   salt	Uma cadeia salt especial utilizada para calcular um hash de segurança.
   sig	Um hash de segurança calculado usado para comparação com seu próprio hash calculado.

2. Verifique se a solicitação vem do Gerenciamento de API do Azure (opcional, mas altamente recomendado para segurança).

   • Calcule um HMAC-SHA512 de uma cadeia de caracteres com base nos parâmetros de consulta productId e userId (ou subscriptionId) e salt:

     Para Assinar:

     HMAC(salt + '\n' + productId + '\n' + userId)
     

     Para Cancelar a assinatura:

     HMAC(salt + '\n' + subscriptionId)
     

   • Compare o hash calculado acima ao valor do parâmetro de consulta sig. Se os dois hashes corresponderem, vá para a próxima etapa. Caso contrário, recuse a solicitação.

3. Processe a assinatura do produto com base no tipo de operação solicitada em operation (por exemplo, faturamento, perguntas complementares, etc.).

4. Depois de concluir a operação do seu lado, gerencie o usuário no Gerenciamento de API. Após fazer com que o usuário assine o produto do seu lado com êxito, faça com que ele assine o produto de Gerenciamento de API chamando a API REST para assinaturas.

Código de exemplo

Esses exemplos de código mostram como gerar o hash do parâmetro de consulta returnUrl ao delegar a entrada ou inscrição do usuário. O returnUrl é o URL da página onde o usuário clicou no link de login ou cadastro.

• Pegue a chave de validação de delegação, definida na tela Delegação do portal do Azure.
• Crie um HMAC que valide a assinatura e comprove a validade do dado fornecido returnUrl.

Com uma pequena modificação, você pode usar o mesmo código para calcular outros hashes, como com productId e userId ao delegar a assinatura do produto.

Código C# para gerar hash de returnUrl

using System.Security.Cryptography;

string key = "delegation validation key";
string returnUrl = "returnUrl query parameter";
string salt = "salt query parameter";
string signature;
using (var encoder = new HMACSHA512(Convert.FromBase64String(key)))
{
    signature = Convert.ToBase64String(encoder.ComputeHash(Encoding.UTF8.GetBytes(salt + "\n" + returnUrl)));
    // change to (salt + "\n" + productId + "\n" + userId) when delegating product subscription
    // compare signature to sig query parameter
}

Código do Node.js para gerar um hash de returnUrl

var crypto = require('crypto');

var key = 'delegation validation key'; 
var returnUrl = 'returnUrl query parameter';
var salt = 'salt query parameter';

var hmac = crypto.createHmac('sha512', new Buffer(key, 'base64'));
var digest = hmac.update(salt + '\n' + returnUrl).digest();
// change to (salt + "\n" + productId + "\n" + userId) when delegating product subscription
// compare signature to sig query parameter

var signature = digest.toString('base64');

Conteúdo relacionado

• Saiba mais sobre o portal do desenvolvedor
• Autenticar usando a ID do Microsoft Entra ou com a ID Externa do Microsoft Entra
• Mais perguntas sobre o portal do desenvolvedor? Encontre respostas nas perguntas frequentes.