Come delegare la registrazione utente e la sottoscrizione ai prodottiHow to delegate user registration and product subscription

La delega consente di usare il sito Web esistente per gestire l'accesso e l'iscrizione degli sviluppatori e la sottoscrizione ai prodotti invece di usare la funzionalità incorporata nel portale per sviluppatori.Delegation allows you to use your existing website for handling developer sign-in/sign-up and subscription to products as opposed to using the built-in functionality in the developer portal. Ciò consente al sito Web di avere la proprietà dei dati utente e di eseguire la convalida di questi passaggi in modo personalizzato.This enables your website to own the user data and perform the validation of these steps in a custom way.

Delega dell'accesso e dell'iscrizione degli sviluppatori Delegating developer sign-in and sign-up

Per delegare l'accesso e l'iscrizione degli sviluppatori al sito Web esistente, è necessario creare un endpoint di delega speciale nel sito che funge da punto di ingresso per qualsiasi richiesta avviata dal portale per sviluppatori di Gestione API.To delegate developer sign-in and sign-up to your existing website you will need to create a special delegation endpoint on your site that acts as the entry-point for any such request initiated from the API Management developer portal.

Il flusso di lavoro finale sarà il seguente:The final workflow will be as follows:

  1. Lo sviluppatore fa clic sul collegamento per l'accesso o l'iscrizione nel portale per sviluppatori di Gestione API.Developer clicks on the sign-in or sign-up link at the API Management developer portal
  2. Il browser viene reindirizzato all'endpoint di delega.Browser is redirected to the delegation endpoint
  3. L'endpoint di delega visualizza o reindirizza a sua volta all'interfaccia utente in cui viene richiesto di effettuare l'accesso o l'iscrizione.Delegation endpoint in return redirects to or presents UI asking user to sign-in or sign-up
  4. In caso di esito positivo, l'utente viene reindirizzato alla pagina del portale per sviluppatori di Gestione API da dove è partito.On success, the user is redirected back to the API Management developer portal page they started from

Per iniziare, configurare innanzitutto Gestione API per indirizzare le richieste tramite l'endpoint di delega.To begin, let's first set-up API Management to route requests via your delegation endpoint. Nel portale di pubblicazione Gestione API fare clic su Sicurezza e selezionare la scheda Delega. Fare clic sulla casella di controllo per abilitare "Delega accesso e iscrizione".In the API Management publisher portal, click on Security and then click the Delegation tab. Click the checkbox to enable 'Delegate sign-in & sign-up'.

Pagina Delega

  • Stabilire l'URL dell'endpoint di delega speciale e immetterlo nel campo URL dell'endpoint delega .Decide what the URL of your special delegation endpoint will be and enter it in the Delegation endpoint URL field.
  • Nel campo Chiave di autenticazione delega immettere una chiave privata da usare per calcolare una firma fornita per verifica in modo da garantire che la richiesta provenga effettivamente da Gestione API di Azure.Within the Delegation authentication key field enter a secret that will be used to compute a signature provided to you for verification to ensure that the request is indeed coming from Azure API Management. È quindi possibile fare clic sul pulsante genera in modo che Gestione API generi una chiave in modo casuale.You can click the generate button to have API Managemnet randomly generate a key for you.

È ora necessario creare l'endpoint di delega,Now you need to create the delegation endpoint. che dovrà eseguire diverse operazioni:It has to perform a number of actions:

  1. Ricevere una richiesta nel formato seguente:Receive a request in the following form:

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

    Parametri di query per l'accesso o l'iscrizione:Query parameters for the sign-in / sign-up case:

    • operation: identifica il tipo di richiesta di delega; in questo caso può essere solo di tipo SignInoperation: identifies what type of delegation request it is - it can only be SignIn in this case
    • returnUrl: l'URL della pagina in cui l'utente ha selezionato il collegamento per l'accesso o l'iscrizionereturnUrl: the URL of the page where the user clicked on a sign-in or sign-up link
    • salt: stringa salt speciale usata per il calcolo di un hash di sicurezzasalt: a special salt string used for computing a security hash
    • sig: hash di sicurezza calcolato da usare per il confronto con il proprio hash calcolatosig: a computed security hash to be used for comparison to your own computed hash
  2. Verificare che la richiesta provenga da Gestione API di Azure. Questa operazione è facoltativa ma altamente consigliata per motivi di sicurezza.Verify that the request is coming from Azure API Management (optional, but highly recommended for security)

    • Calcolare un hash HMAC-SHA512 di una stringa in base ai parametri di query returnUrl e salt (il codice di esempio è fornito di seguito):Compute an HMAC-SHA512 hash of a string based on the returnUrl and salt query parameters ([example code provided below]):

      HMAC(salt + '\n' + returnUrl)HMAC(salt + '\n' + returnUrl)

    • Confrontare l'hash sopra calcolato con il valore del parametro di query sig .Compare the above-computed hash to the value of the sig query parameter. Se i due hash corrispondono, procedere con il passaggio successivo; in caso contrario, negare la richiesta.If the two hashes match, move on to the next step, otherwise deny the request.
  3. Verificare la ricezione di una richiesta di accesso o iscrizione: il parametro di query operation verrà impostato su "SignIn".Verify that you are receiving a request for sign-in/sign-up: the operation query parameter will be set to "SignIn".
  4. Visualizzare l'interfaccia utente per effettuare l'accesso o l'iscrizione.Present the user with UI to sign-in or sign-up
  5. Se l'utente sta effettuando un'iscrizione, è necessario creare un account corrispondente in Gestione API.If the user is signing-up you have to create a corresponding account for them in API Management. [Creare un utente] con l'API REST di Gestione API.Create a user with the API Management REST API. Quando si esegue questa operazione, assicurarsi di impostare l'ID utente sullo stesso valore presente nell'archivio utenti o su un ID di cui è possibile tenere traccia.When doing so, ensure that you set the user ID to the same it is in your user store or to an ID that you can keep track of.
  6. Quando l'utente viene autenticato correttamente:When the user is successfully authenticated:

Oltre all'operazione SignIn , è anche possibile eseguire la gestione degli account seguendo i passaggi precedenti e usando una delle operazioni seguenti.In addition to the SignIn operation, you can also perform account management by following the previous steps and using one of the following operations.

  • ChangePasswordChangePassword
  • ChangeProfileChangeProfile
  • CloseAccountCloseAccount

È necessario passare i parametri di query seguenti per le operazioni di gestione di account.You must pass the following query parameters for account management operations.

  • operation: identifica il tipo di richiesta di delega (ChangePassword, ChangeProfile o CloseAccount)operation: identifies what type of delegation request it is (ChangePassword, ChangeProfile, or CloseAccount)
  • userId: ID utente dell'account da gestireuserId: the user id of the account to manage
  • salt: stringa salt speciale usata per il calcolo di un hash di sicurezzasalt: a special salt string used for computing a security hash
  • sig: hash di sicurezza calcolato da usare per il confronto con il proprio hash calcolatosig: a computed security hash to be used for comparison to your own computed hash

Delega della sottoscrizione ai prodotti Delegating product subscription

La delega della sottoscrizione ai prodotti funziona in modo analogo alla delega dell'accesso o dell'iscrizione.Delegating product subscription works similarly to delegating user sign-in/-up. Il flusso di lavoro finale sarà il seguente:The final workflow would be as follows:

  1. Lo sviluppatore seleziona un prodotto nel portale per sviluppatori di Gestione API e fa clic sul pulsante Sottoscrivi.Developer selects a product in the API Management developer portal and clicks on the Subscribe button
  2. Il browser viene reindirizzato all'endpoint di delega.Browser is redirected to the delegation endpoint
  3. L'endpoint di delega esegue i passaggi necessari per la sottoscrizione ai prodotti. È possibile scegliere i passaggi da eseguire, ad esempio se reindirizzare a un'altra pagina per richiedere le informazioni di fatturazione, se porre altre domande o semplicemente se archiviare le informazioni senza richiedere alcun intervento da parte dell'utente.Delegation endpoint performs required product subscription steps - this is up to you and may entail redirecting to another page to request billing information, asking additional questions, or simply storing the information and not requiring any user action

Per abilitare la funzionalità, nella pagina Delega fare clic su Delega sottoscrizione ai prodotti.To enable the functionality, on the Delegation page click Delegate product subscription.

Assicurarsi quindi che l'endpoint di delega esegua le operazioni seguenti:Then ensure the delegation endpoint performs the following actions:

  1. Ricevere una richiesta nel formato seguente:Receive a request in the following form:

    http://www.yourwebsite.com/apimdelegation?operation={operazione}&productId={prodotto per il quale effettuare la sottoscrizione}&userId={utente che esegue la richiesta}&salt={stringa}&sid={stringa}http://www.yourwebsite.com/apimdelegation?operation={operation}&productId={product to subscribe to}&userId={user making request}&salt={string}&sig={string}

    Parametri di query per la sottoscrizione ai prodotti:Query parameters for the product subscription case:

    • operation: identifica il tipo di richiesta di delega.operation: identifies what type of delegation request it is. Per le richieste di sottoscrizione ai prodotti le opzioni valide sono:For product subscription requests the valid options are:
      • "Subscribe": richiesta di sottoscrizione a un prodotto specifico con l'ID fornito (vedere sotto)"Subscribe": a request to subscribe the user to a given product with provided ID (see below)
      • "Unsubscribe": richiesta di annullamento della sottoscrizione a un prodotto"Unsubscribe": a request to unsubscribe a user from a product
      • "Renew": richiesta di rinnovo di una sottoscrizione, ad esempio perché è scaduta"Renew": a requst to renew a subscription (e.g. that may be expiring)
    • productId: ID del prodotto a cui effettuare la sottoscrizioneproductId: the ID of the product the user requested to subscribe to
    • userId: ID dell'utente per il quale viene eseguita la richiestauserId: the ID of the user for whom the request is made
    • salt: stringa salt speciale usata per il calcolo di un hash di sicurezzasalt: a special salt string used for computing a security hash
    • sig: hash di sicurezza calcolato da usare per il confronto con il proprio hash calcolatosig: a computed security hash to be used for comparison to your own computed hash
  2. Verificare che la richiesta provenga da Gestione API di Azure. Questa operazione è facoltativa ma altamente consigliata per motivi di sicurezza.Verify that the request is coming from Azure API Management (optional, but highly recommended for security)

    • Calcolare un hash HMAC-SHA512 di una stringa in base ai parametri di query productId, userId e salt:Compute an HMAC-SHA512 of a string based on the productId, userId and salt query parameters:

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

    • Confrontare l'hash sopra calcolato con il valore del parametro di query sig .Compare the above-computed hash to the value of the sig query parameter. Se i due hash corrispondono, procedere con il passaggio successivo; in caso contrario, negare la richiesta.If the two hashes match, move on to the next step, otherwise deny the request.
  3. Eseguire una qualsiasi elaborazione della sottoscrizione al prodotto in base al tipo di operazione richiesta in operation , ad esempio fatturazione, altre domande e così via.Perform any product subscription processing based on the type of operation requested in operation - e.g. billing, further questions, etc.
  4. Dopo la corretta sottoscrizione al prodotto in locale, effettuare la sottoscrizione al prodotto in Gestione API chiamando l'API REST per la sottoscrizione al prodotto.On successfully subscribing the user to the product on your side, subscribe the user to the API Management product by [calling the REST API for product subscription].

Codice di esempio Example Code

I codici di esempio seguenti illustrano come usare la chiave di convalida della delega, impostata nella schermata Delega del portale di pubblicazione, per creare un HMAC che viene quindi usato per convalidare la firma, dimostrando la validità del returnUrl passato.These code samples show how to take the delegation validation key, which is set in the Delegation screen of the publisher portal, to create a HMAC which is then used to validate the signature, proving the validity of the passed returnUrl. Lo stesso codice funziona per productId e userId con leggeri modifiche.The same code works for the productId and userId with slight modification.

Codice C# per generare l'hash di returnUrlC# code to generate hash of 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
}

Codice NodeJS per generare l'hash di returnUrlNodeJS code to generate hash of 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');

Passaggi successiviNext steps

Per altre informazioni sulla delega, vedere il video seguente.For more information on delegation, see the following video.