Come delegare la registrazione utente e la sottoscrizione ai prodotti

SI APPLICA A: Sviluppatore | Basic | Standard | Premium

La delega consente al sito Web di possedere i dati utente ed eseguire la convalida personalizzata. Con la delega, è possibile gestire l'accesso o l'iscrizione degli sviluppatori (e le relative operazioni di gestione degli account) e la sottoscrizione del prodotto usando il sito Web esistente, anziché la funzionalità predefinita del portale per sviluppatori.

Delega dell'accesso e dell'iscrizione degli sviluppatori

Per delegare le opzioni di accesso e iscrizione e gestione degli account per sviluppatori al sito Web esistente, creare un endpoint di delega speciale nel sito. Questa delega speciale funge da punto di ingresso per qualsiasi accesso/iscrizione e richieste correlate avviate dal portale per sviluppatori di Gestione API.

Il flusso di lavoro finale sarà:

1. Lo sviluppatore fa clic sul collegamento di accesso o iscrizione o su un collegamento di gestione degli account nel portale per sviluppatori di Gestione API.
2. Il browser reindirizza all'endpoint di delega.
3. L'endpoint di delega, in cambio, reindirizza l'utente a o presenta all'utente l'interfaccia utente di accesso/iscrizione o gestione degli account.
4. Al termine dell'operazione, l'utente viene reindirizzato al portale per sviluppatori di Gestione API nella posizione lasciata.

Configurare Gestione API per instradare le richieste tramite l'endpoint di delega

1. Nel portale di Azure cercare Portale per sviluppatori nella risorsa gestione API.

2. Fare clic sull'elemento Delega .

3. Fare clic sulla casella di controllo per abilitare Delega accesso e iscrizione.

   

4. Decidere l'URL dell'endpoint di delega speciale e immetterlo nel campo URL dell'endpoint di delega.

5. All'interno del campo chiave di convalida della delega:

   • Immettere un segreto usato per calcolare una firma fornita per verificare che la richiesta proviene da Gestione API.
   • Fare clic sul pulsante Genera per Gestione API per generare automaticamente una chiave casuale.

6. Fare clic su Salva.

Creare l'endpoint di delega

Procedura consigliata per la creazione di un nuovo endpoint di delega da implementare nel sito:

1. Ricevere una richiesta nel formato seguente, a seconda dell'operazione:

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

   Oppure

   http://www.yourwebsite.com/apimdelegation?operation={operation}&userId={user ID of account}&salt={string}&sig={string}

   Parametri di query:

   Parametro	Descrizione
   operation	Identifica il tipo di richiesta di delega. Operazioni disponibili: Accesso, Iscrizione, Cambia password, Cambia Profilo, Chiudi Account, Esci.
   returnUrl	In Accesso o Iscrizione, l'URL del punto in cui l'utente ha fatto clic su un collegamento di accesso o iscrizione.
   userId	In Cambia Password, Cambia Profilo, Chiudi Account e Esci, l'ID utente dell'account che si vuole gestire.
   salt	Stringa salt speciale usata per il calcolo di un hash di sicurezza.
   sig	Hash di sicurezza calcolato, usato per il confronto con il proprio hash calcolato.

2. Verificare che la richiesta provenga da Gestione API di Azure (facoltativa, ma altamente consigliata per la sicurezza).

   • Calcolare un hash HMAC-SHA512 di una stringa in base ai parametri di query returnUrl (o UserId) e salt. Per esempi, controllare il codice di esempio.

     Per Accedi e Iscriviti:

     HMAC(salt + '\n' + returnUrl)
     

     Per Cambia Password, Cambia Profilo, Chiudi Account ed Esci:

     HMAC(salt + '\n' + userId)
     

   • Confrontare l'hash sopra calcolato con il valore del parametro di query sig . Se i due hash corrispondono, passare al passaggio successivo. In caso contrario, negare la richiesta.

3. Verificare di ricevere una richiesta per un'operazione di accesso/iscrizione o gestione degli account.

4. Presentare all'utente l'interfaccia utente di accesso/iscrizione o gestione degli account.

5. Dopo aver completato l'operazione sul lato, gestire l'utente in Gestione API. Ad esempio, se l'utente effettua l'iscrizione, creare un account corrispondente in Gestione API.

   • Creare un utente con l'API REST di Gestione API.
   • Impostare l'ID utente sullo stesso valore nell'archivio utenti o su un nuovo ID facilmente monitorato.

6. Dopo l'accesso o l'iscrizione, quando l'utente viene autenticato correttamente:

   • Richiedere un token di accesso condiviso tramite l'API REST di Gestione API.

   • Aggiungere un parametro di query returnUrl all'URL SSO ricevuto dalla chiamata API precedente. Ad esempio:

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

   • Reindirizzare l'utente all'URL generato in precedenza.

Delega della sottoscrizione ai prodotti

La delega della sottoscrizione ai prodotti funziona in modo analogo alla delega dell'accesso o dell'iscrizione dell’utente. Il flusso di lavoro finale sarà il seguente:

1. Lo sviluppatore seleziona un prodotto nel portale per sviluppatori di Gestione API e fa clic sul pulsante Sottoscrivi.
2. Il browser reindirizza all'endpoint di delega.
3. L'endpoint di delega esegue i passaggi necessari per la sottoscrizione del prodotto, che si progetta. Possono includere:
   • Reindirizzamento a un'altra pagina per richiedere informazioni di fatturazione.
   • Porre domande aggiuntive.
   • Archiviazione delle informazioni e nessuna azione richiesta da parte dell'utente.

Abilitare la funzionalità Gestione API

Nella pagina Delega fare clic su Delega sottoscrizione del prodotto.

Creare l'endpoint di delega

Procedura consigliata per la creazione di un nuovo endpoint di delega da implementare nel sito:

1. Ricevere una richiesta nel formato seguente, a seconda dell'operazione.

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

   Oppure

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

   Parametri di query:

   Parametro	Descrizione
   operation	Identifica il tipo di richiesta di delega. Le opzioni per le richieste di sottoscrizione del prodotto valide sono: Sottoscrivi: una richiesta di sottoscrizione dell'utente a un determinato prodotto con l'ID specificato (vedere di seguito). Annulla la sottoscrizione: richiesta di annullare la sottoscrizione di un utente a un prodotto
   productId	In Sottoscrivi, l'ID del prodotto che l'utente ha richiesto di sottoscrivere.
   userId	In Sottoscrivi, l'ID dell'utente richiedente.
   subscriptionId	In Annulla la sottoscrizione, l'ID di sottoscrizione del prodotto.
   salt	Stringa salt speciale usata per il calcolo di un hash di sicurezza.
   sig	Hash di sicurezza calcolato, usato per il confronto con il proprio hash calcolato.

2. Verificare che la richiesta provenga da Gestione API di Azure. Questa operazione è facoltativa ma altamente consigliata per motivi di sicurezza.

   • Calcolare un valore HMAC-SHA512 di una stringa in base al productId e userId (o subscriptionId) e parametri di query salt:

     Per Sottoscrivi:

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

     Per Annulla la sottoscrizione:

     HMAC(salt + '\n' + subscriptionId)
     

   • Confrontare l'hash sopra calcolato con il valore del parametro di query sig . Se i due hash corrispondono, passare al passaggio successivo. In caso contrario, negare la richiesta.

3. Elaborare la sottoscrizione del prodotto in base al tipo di operazione richiesto nell'operazione (ad esempio: fatturazione, altre domande e così via).

4. Dopo aver completato l'operazione sul lato, gestire la sottoscrizione in Gestione API. Ad esempio, sottoscrivere l'utente al prodotto Gestione API chiamando l'API REST per le sottoscrizioni.

Codice di esempio

Questi esempi di codice illustrano come generare l'hash del parametro di query returnUrl durante la delega dell'accesso o dell'iscrizione utente. returnUrl è l'URL della pagina in cui l'utente ha fatto clic sul collegamento di accesso o iscrizione.

• Prendere la chiave di convalida della delega, impostata nella schermata Delega del portale di Azure.
• Creare un HMAC, che convalida la firma, dimostrando la validità del returnUrl passato.

Con una leggera modifica, è possibile usare lo stesso codice per calcolare altri hash, ad esempio con productId e userId quando si delega la sottoscrizione del prodotto.

Codice C# per generare l'hash di 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 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

Per rendere effettive le modifiche della delega, è necessario ripubblicare il portale per sviluppatori.

Passaggi successivi

• Altre informazioni sul portale per sviluppatori.
• Eseguire l'autenticazione con Microsoft Entra ID o con Azure AD B2C.
• Altre domande sul portale per sviluppatori? Trovare le risposte nelle domande frequenti.