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

  • Artigo

APLICA-SE A: Desenvolvedor | Básico | Standard | Premium

A delegação permite que o seu site tenha os dados dos usuários e realize a validação personalizada. Com a delegação, você pode lidar com o logon/inscrição do desenvolvedor (e operações de gerenciamento de contas relacionadas) e com a assinatura do produto usando seu site existente, em vez da funcionalidade integrada 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 o ponto de entrada para qualquer solicitação de entrada/inscrição iniciada no portal do desenvolvedor do Gerenciamento de API.

O fluxo de trabalho final será:

  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 para ou apresenta ao usuário 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, procure Portal do desenvolvedor no recurso do Gerenciamento de API.

  2. Clique no item Delegação.

  3. Clique na caixa de seleção para habilitar a opção Delegar entrada e inscrição.

    Captura de tela mostrando a delegação de logon e o registro no portal.

  4. Decida a URL do seu ponto de extremidade de delegação especial e insira-a no campo URL do ponto de extremidade de delegação.

  5. No campo Chave de Validação de Delegação, faça um dos seguintes:

    • Insira um segredo usado para calcular uma assinatura fornecida para verificação de que a solicitação se origina do Gerenciamento de API.
    • Clique no botão Gerar para o Gerenciamento de API a fim de gerar uma chave aleatória para você.

  6. Clique em Save (Salvar).

Criar seu ponto de extremidade de delegação

Etapas recomendadas para a criação de um novo ponto de extremidade de delegação a ser implementado em seu site:

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

    http://www.yourwebsite.com/apimdelegation?operation={operation}&returnUrl={URL of source page}&salt={string}&sig={string}

    -Ou-

    http://www.yourwebsite.com/apimdelegation?operation={operation}&userId={user ID of account}&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.
    sal Uma cadeia de caracteres de salt especial usada 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. 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 Entrada e Inscrição:

      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 seria o seguinte:

  1. O desenvolvedor seleciona um produto no portal do desenvolvedor do Gerenciamento de API e clica no 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. São exemplos de etapa:
    • Redirecionar para outra página a fim de solicitar informações de cobrança.
    • Fazer perguntas adicionais.
    • 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, clique em Delegar assinatura do produto.

Criar seu ponto de extremidade de delegação

Etapas recomendadas para a criação de um novo ponto de extremidade de delegação a ser implementado em seu site:

  1. Receba 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 de solicitações de assinatura do produto válidas 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.
    sal Uma cadeia de caracteres de salt especial usada 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. Confirme que a solicitação está vindo do Gerenciamento de API do Azure (opcional, mas altamente recomendado por 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 forem correspondentes, prossiga 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 returnUrl parâmetro de consulta ao delegar a entrada ou inscrição do usuário. A returnUrl é a URL da página em que o usuário clicou em um link de entrada ou de inscrição.

  • Pegue a chave de validação de delegação, definida na tela Delegação do portal do Azure.
  • Criar um HMAC, que valida a assinatura, comprovando a validade da returnUrl passada.

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 NodeJS para gerar 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');

Importante

Você precisa republicar o portal do desenvolvedor para que as alterações de delegação entrem em vigor.

Próximas etapas