Condividi tramite

Come delegare la registrazione utente e la sottoscrizione ai prodotti

SI APPLICA A: Sviluppatore | Basic | Basic v2 | Standard | Standard v2 | Premium | Premium v2

La delega consente al sito Web di possedere i dati utente ed eseguire la convalida personalizzata per gli utenti del portale per sviluppatori. Con la delega, è possibile gestire l'accesso e 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 di accesso e 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 è costituito da questi passaggi:

  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 un endpoint di delega

  1. Nel portale di Azure passare all'istanza di Gestione API.

  2. Nel menu della barra laterale, in Portale per sviluppatori, selezionare Delega.

  3. Selezionare la casella di controllo Abilita delega.

  4. Selezionare la casella di controllo per abilitare l'accesso delegato e l'iscrizione.

    Screenshot che mostra la delega dell'accesso e dell'iscrizione nel portale.

  5. Scegliere l'URL per il proprio endpoint speciale di delega e immetterlo nel campo endpoint del servizio di delega.

  6. In Chiavi di delega:

    • Generare la chiave di convalida primaria o la chiave di convalida secondaria (o entrambe) da usare dal servizio di delega per convalidare le richieste da Gestione API. Selezionare i puntini di sospensione (...) accanto a una delle due chiavi e quindi selezionare Riscrivere.
    • Selezionare i puntini di sospensione (...) accanto a una delle due chiavi e quindi selezionare Copia. Copiare le chiavi in una posizione sicura e usarle durante la configurazione del servizio di delega.

  7. Seleziona Salva.

Suggerimento

È possibile ruotare e rigenerare le chiavi di convalida della delega in qualsiasi momento. La rotazione sostituisce la chiave primaria con la chiave secondaria e rigenera la chiave secondaria. Dopo aver salvato le chiavi, assicurarsi di aggiornare il servizio di delega per usare le nuove chiavi.

Creare l'endpoint di delega

Per creare un nuovo endpoint di delega da implementare nel sito, seguire questa procedura:

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

    http://www.yourwebsite.com/apimdelegation?operation={operation}& returnUrl={URL della pagina di origine}&salt={string}&sig={string}

    Oppure

    http://www.yourwebsite.com/apimdelegation?operation={operation}& userId={ID utente dell'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 è costituito da questi passaggi:

  1. Lo sviluppatore seleziona un prodotto nel portale per sviluppatori di Gestione API e seleziona il 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. Questi passaggi possono includere:
    • Reindirizzamento a un'altra pagina per richiedere informazioni di fatturazione.
    • Porre ulteriori domande.
    • Archiviazione delle informazioni e nessuna azione richiesta da parte dell'utente.

Abilitare la funzionalità Gestione API

Nella pagina Delega, selezionare la casella di controllo Abilita delega e quindi abilitare Delega sottoscrizione prodotto.

Creare l'endpoint di delega

Per creare un nuovo endpoint di delega per il sito, seguire questa procedura:

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

    http://www.yourwebsite.com/apimdelegation?operation={operation}&productId={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 di richiesta 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 (facoltativa, ma altamente consigliata per la 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 per convalidare la firma e dimostrare la validità dell'elemento passato returnUrl.

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 Node.js 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.

Contenuti correlati

  • Last updated on