Como delegar o registo de utilizador e a subscrição de produtos

APLICA-SE A: Developer | Basic | Basic v2 | Standard | Standard v2 | Premium | Premium v2

A delegação permite que seu site seja proprietário dos 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 o login 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.

Delegando o login e a inscrição do desenvolvedor

Para delegar as opções de início de sessão, inscrição e gestão de contas de desenvolvedor ao seu website existente, crie um ponto de extremidade especial de delegação no seu site. Essa delegação especial atua como o ponto de entrada para qualquer entrada/inscrição e solicitações relacionadas iniciadas a partir do portal do desenvolvedor do Gerenciamento de API.

O fluxo de trabalho final consiste nestas etapas:

1. O programador clica no link de início de sessão ou de registo ou num link de gestão de conta no portal de programadores da Gestão de API.
2. O navegador redireciona para o ponto final da delegação.
3. O endpoint de delegação, por sua vez, redireciona o utilizador ou apresenta a interface de utilizador para iniciar sessão/inscrever-se ou de gestão de conta.
4. Após a conclusão da operação, o usuário é redirecionado de volta para o portal do desenvolvedor do Gerenciamento de API no local que saiu.

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

1. No portal do Azure, vá para sua instância de Gerenciamento de API.

2. No menu da barra lateral, em Portal do desenvolvedor, selecione Delegação.

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

4. Marque a caixa de seleção para ativar Início de sessão e registo delegado.

   

5. Escolha o URL para o seu endpoint especial de delegação e introduza-o no campo Endpoint 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) para usar pelo serviço de delegação para validar solicitações do Gerenciamento de API. Selecione a reticência (...) ao lado de qualquer tecla e, em seguida, selecione Regenerar.
   • Selecione as reticências (...) junto a qualquer das teclas e, em seguida, selecione Copiar. Copie as chaves para um local seguro e use-as ao configurar o serviço de delegação.

7. Selecione Guardar.

Crie o seu ponto final de delegação

Para criar um novo ponto de extremidade de delegação para implementar no seu site, siga estas etapas:

1. Receberá um pedido da seguinte forma, 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
   Funcionamento	Identifica o tipo de solicitação de delegação. Operações disponíveis: SignIn, SignUp, ChangePassword, ChangeProfile, CloseAccount, SignOut.
   returnUrl	Em Login ou Inscrição, a URL de onde o usuário clicou em um link de entrada ou inscrição.
   userId	Em ChangePassword, ChangeProfile, CloseAccount e SignOut, o ID de usuário da conta que você deseja gerenciar.
   sal	Uma cadeia de sal especial usada para calcular um hash de segurança.
   sig	Um hash de segurança computado usado para comparação com seu próprio hash computado.

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

   • Calcule um hash HMAC-SHA512 de uma cadeia de caracteres com base nos parâmetros returnUrl (ou UserId) e salt query. Para exemplos, verifique nosso código de exemplo.

     Para Login e Inscrição:

     HMAC(salt + '\n' + returnUrl)
     

     Para ChangePassword, ChangeProfile, CloseAccount e SignOut:

     HMAC(salt + '\n' + userId)
     

   • Compare o hash calculado acima com o valor do parâmetro de consulta sig . Se os dois hashes corresponderem, passe para a próxima etapa. Caso contrário, negue o pedido.

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

4. Apresente ao utilizador a interface de iniciar sessão/inscrever-se ou gestão de conta.

5. Depois de concluir a operação do seu lado, gerencie o usuário no 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 de gerenciamento de API.
   • Defina o ID de usuário para o mesmo valor em seu repositório de usuário ou um novo ID facilmente rastreável.

6. Após o início de sessão ou registo, quando o utilizador for autenticado com êxito:

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

   • Anexe um parâmetro de consulta returnUrl à URL de SSO recebida da chamada de API acima. Por exemplo:

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

   • Redirecione o usuário para o URL produzido acima.

Delegando a assinatura do produto

A delegação de subscrições de produtos funciona de forma semelhante à delegação de início de sessão/registo de utilizadores. 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 final da delegação.
3. O endpoint de delegação executa os passos necessários de subscrição do produto, que são por si projetadas. Essas etapas podem incluir:
   • Redirecionar para outra página para solicitar informações de cobrança.
   • Fazer mais perguntas.
   • Armazenar as informações e não exigir qualquer ação do usuário.

Habilitar a funcionalidade de Gerenciamento de API

Na página Delegação , marque a caixa de seleção Habilitar delegação e habilite Delegar assinatura de produto.

Crie o seu ponto final de delegação

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

1. Receba um pedido no seguinte formato, de acordo com a operação.

   http://www.yourwebsite.com/apimdelegation?operation={operation}&productId={produto para assinar}&userId={utilizador a fazer o pedido}&salt={string}&sig={string}

   -Ou-

   http://www.yourwebsite.com/apimdelegation?operation={operation}&subscriptionId={assinatura para gerir}&salt={string}&sig={string}

   Parâmetros de consulta:

   Parâmetro	Descrição
   Funcionamento	Identifica o tipo de solicitação de delegação. As opções de solicitação de assinatura de produto válidas são: Subscrever: um pedido para subscrever o utilizador de um determinado produto com ID fornecido (ver abaixo). Cancelar inscrição: uma solicitação para cancelar a assinatura de um usuário de um produto
   ID de produto	Em Subscrever, o ID do produto que o utilizador solicitou a subscrição.
   userId	Em Subscrever, o ID do utilizador requerente.
   ID de subscrição	Em Cancelar inscrição, o ID da assinatura do produto.
   sal	Uma cadeia de sal especial usada para calcular um hash de segurança.
   sig	Um hash de segurança computado usado para comparação com seu próprio hash computado.

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

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

     Para Subscrever:

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

     Para cancelar inscrição:

     HMAC(salt + '\n' + subscriptionId)
     

   • Compare o hash calculado acima com o valor do parâmetro de consulta sig . Se os dois hashes corresponderem, passe para a próxima etapa. Caso contrário, negue o pedido.

3. Processar a assinatura do produto com base no tipo de operação solicitada na operação (por exemplo: faturamento, outras perguntas, etc.).

4. Depois de concluir a operação do seu lado, gerencie a assinatura no Gerenciamento de API. Por exemplo, inscreva o usuário no produto 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 utilizador. O returnUrl é o URL da página onde o utilizador clicou na ligação de início de sessão ou de registo.

• Pegue a chave de validação de delegação, que você define na tela Delegação do portal do Azure.
• Crie um HMAC, que valida a assinatura e comprova a validade do 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
}

Node.js código 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');

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 nossas Perguntas Frequentes.