Como delegar o registo de utilizador e a subscrição do produto

APLICA-SE A: Developer | Básico | Padrão | Prémio

A delegação permite que seu site seja proprietário dos dados do usuário e execute a validação personalizada. Com a delegação, você pode lidar com o login/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 programador ao seu Web 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 entrada/inscrição e solicitações relacionadas iniciadas a partir do portal do desenvolvedor do Gerenciamento de API.

O fluxo de trabalho final será:

1. O desenvolvedor clica no link de entrada ou 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 de delegação.
3. O ponto de extremidade de delegação, em troca, redireciona o usuário ou apresenta a interface do usuário de login/inscrição ou gerenciamento 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 via ponto de extremidade de delegação

1. No portal do Azure, procure Portal do desenvolvedor em seu recurso de Gerenciamento de API.

2. Clique no item Delegação .

3. Clique na caixa de seleção para habilitar o logon delegado & inscrição.

   

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

5. No campo Chave de Validação de Delegação:

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

6. Clique em Guardar.

Crie seu ponto de extremidade de delegação

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

1. Receba 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	Description
   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 usuário a interface do usuário de login/inscrição ou gerenciamento de contas.

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/inscrição de utilizadores. 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 de delegação.
3. O ponto de extremidade de delegação executa as etapas necessárias de assinatura do produto, que você projeta. Podem incluir:
   • Redirecionar para outra página para solicitar informações de cobrança.
   • Fazer perguntas adicionais.
   • 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, clique em Delegar assinatura de produto.

Crie seu ponto de extremidade de delegação

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

1. Receba um pedido no seguinte formulário, dependendo da operação.

   http://www.yourwebsite.com/apimdelegation?operation={operation}&p roductId={produto para assinar}&userId={user making request}&salt={string}&sig={string}

   -Ou-

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

   Parâmetros de consulta:

   Parâmetro	Description
   Funcionamento	Identifica o tipo de solicitação de delegação. As opções de pedidos de subscrição de produtos válidos 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
   productId	Em Subscrever, o ID do produto que o utilizador solicitou a subscrição.
   userId	Em Subscrever, o ID do utilizador requerente.
   subscriptionId	Em Cancelar inscrição, a 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 está vindo 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 productId e userId (ou subscriptionId) e consulta 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 ao delegar a entrada ou inscrição returnUrl do usuário. O returnUrl é o URL da página em que 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 é definida na tela Delegação do portal do Azure.
• Crie um HMAC, que valida a assinatura, comprovando a validade do returnUrl passado.

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 o 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 o 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 publicar novamente o portal do desenvolvedor para que as alterações de delegação entrem em vigor.

Próximos passos

• Saiba mais sobre o portal do desenvolvedor.
• Autentique-se usando a ID do Microsoft Entra ou com o Azure AD B2C.
• Mais perguntas sobre o portal do desenvolvedor? Encontre respostas nas nossas Perguntas Frequentes.