Eseguire l'autenticazione con le API REST di Mobile Engagement

Panoramica

Il presente documento descrive come ottenere un token Oauth AAD per eseguire l'autenticazione con le API REST di Mobile Engagement.

Si presuppone che l'utente abbia una sottoscrizione di Azure valida e che abbia creato un'app Mobile Engagement usando una delle Esercitazioni per sviluppatori.

Autenticazione

È necessario usare per l'autenticazione un token OAuth basato su Microsoft Azure Active Directory.

Per autenticare richieste API, è necessario aggiungere un'intestazione di autorizzazione a ciascuna richiesta della seguente forma:

Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGmJlNmV2ZWJPamg2TTNXR1E...
Nota

I token di Azure Active Directory scadono in un'ora.

È possibile ottenere un token in diversi modi: Dal momento che le API vengono in genere chiamate da un servizio cloud, si vorrà usare una chiave API. Nella terminologia di Azure una chiave API è una password dell'entità servizio. La procedura seguente descrive come impostarla in modo manuale.

Installazione singola (mediante script)

È necessario osservare le istruzioni seguenti per eseguire l'installazione tramite uno script di PowerShell che richiede il minor tempo ma che utilizza le impostazioni predefinite più ammissibili. Facoltativamente, è anche possibile seguire le istruzioni per l'installazione manuale per eseguire questa operazione direttamente dal portale di Azure con una configurazione più precisa.

  1. Usare la versione più recente di Azure PowerShell che può essere scaricata qui. Per ulteriori informazioni sulle istruzioni di download, è possibile visualizzare questo collegamento.
  2. Dopo aver installato Azure PowerShell, usare i comandi seguenti per assicurarsi che il modulo Azure sia installato:

    a. Assicurarsi che il modulo Azure PowerShell sia presente nell'elenco dei moduli disponibili.

     Get-Module –ListAvailable 
    

    Moduli di Azure disponibili

    b. Se il modulo Azure PowerShell non è presente nell'elenco precedente, è necessario procedere come segue:

     Import-Module Azure 
    
  3. Accedere ad Azure Resource Manager da PowerShell eseguendo il comando seguente e fornendo nome utente e password dell'account Azure:

     Login-AzureRmAccount
    
  4. In caso di più sottoscrizioni, procedere come segue:

    a. Ottenere un elenco di tutte le sottoscrizioni e copiare il SubscriptionId della sottoscrizione che si desidera utilizzare. Assicurarsi che la sottoscrizione corrisponda a quella dell'app Mobile Engagement con cui si andrà a interagire tramite le API.

     Get-AzureRmSubscription
    

    b. Eseguire il comando seguente specificando il SubscriptionId per configurare la sottoscrizione da usare.

     Select-AzureRmSubscription –SubscriptionId <subscriptionId>
    
  5. Copiare il testo per lo script New-AzureRmServicePrincipalOwner.ps1 nel computer locale, salvarlo come cmdlet PowerShell (ad esempio APIAuth.ps1) ed eseguirlo .\APIAuth.ps1.
  6. Lo script richiederà di immettere un principalName. Fornire un nome adeguato da utilizzare per creare l'applicazione Active Directory (ad esempio APIAuth).
  7. Dopo il completamento dello script, accertarsi di copiare i quattro valori seguenti che verranno visualizzati, necessari per un'autenticazione a livello di codice con AD

    TenantId, SubscriptionId, ApplicationId e Secret.

    TenantId sarà usato come {TENANT_ID}, ApplicationId come {CLIENT_ID} e Secret come {CLIENT_SECRET}.

    Nota

    I criteri di sicurezza predefiniti possono bloccare l'esecuzione degli script PowerShell. In questo caso, configurare temporaneamente i criteri di esecuzione in modo da consentire l'esecuzione degli script usando il comando seguente:

    Set-ExecutionPolicy RemoteSigned

  8. L'insieme di cmdlet PS sarà simile al seguente.

  9. Controllare nel portale di gestione di Azure che sia stata creata una nuova applicazione AD con il nome specificato per lo script denominato principalName in Mostra Applicazioni di proprietà dell'azienda.

Procedura per ottenere un token valido

  1. Chiamare l'API con i parametri seguenti e assicurarsi di sostituire TENANT_ID, CLIENT_ID e CLIENT_SECRET:

    • URL richiesta come https://login.microsoftonline.com/{TENANT_ID}/oauth2/token
    • Intestazione Content-Type HTTP come application/x-www-form-urlencoded
    • Corpo richiesta HTTP come grant_type=client_credentials&client_id={CLIENT_ID}&client_secret={CLIENT_SECRET}&resource=https%3A%2F%2Fmanagement.core.windows.net%2F

      Di seguito è riportata una richiesta di esempio:

      POST / {TENANT_ID} / oauth2/token Host HTTP/1.1: login.microsoftonline.com Content-Type: grant_type application/x-www-form-urlencoded = client_credentials & client_id = {CLIENT_ID} & client_secret = {CLIENT_SECRET} & reso urce=https%3A%2F%2Fmanagement.core.windows.net%2F

      Di seguito è riportata una risposta di esempio:

      HTTP/1.1 200 OK Content-Type: application/json; charset = utf-8. Content-Length: 1234

      {"token_type":"Bearer","expires_in":"3599","expires_on":"1445395811","not_before":"144 5391911","resource":"https://management.core.windows.net/","access_token":{ACCESS_TOKEN}}

      Questo esempio include la codifica URL dei parametri POST. Il valore resource effettivo è https://management.core.windows.net/. Prestare attenzione anche alla codifica URL di {CLIENT_SECRET} perché può contenere caratteri speciali.

      Nota

      Per i test, è possibile usare uno strumento client HTTP come Fiddler o l'estensione Chrome Postman

  2. Ora in ogni chiamata all'API includere l'intestazione della richiesta di autorizzazione:

     Authorization: Bearer {ACCESS_TOKEN}
    

    Se viene restituito il codice di stato 401, rivedere il corpo della risposta e controllare che il token non sia scaduto. In caso affermativo, ottenere un nuovo token.

Uso delle API

Ora che si dispone di un token valido, è possibile eseguire chiamate API.

  1. È necessario passare in ciascuna richiesta API un token valido e non scaduto, ottenuto nella sezione precedente.
  2. È necessario inserire alcuni parametri nella richiesta URI che identifica l'applicazione. L'URI di richiesta è simile al seguente:

     https://management.azure.com/subscriptions/{subscription-id}/resourcegroups/{resource-group-name}/
     providers/Microsoft.MobileEngagement/appcollections/{app-collection}/apps/{app-resource-name}/
    

    Per ottenere i parametri, fare clic sul nome dell'applicazione e quindi su Dashboard. Verrà visualizzata una pagina simile a quella riportata di seguito, con tutti e tre i parametri.

    • 1 {subscription-id}
    • 2 {app-collection}
    • 3 {app-resource-name}
    • 4Il nome del gruppo di risorse sarà MobileEngagement a meno che non ne sia stato creato uno nuovo.

      Parametri URI API di Mobile Engagement

Nota


  1. Ignorare l'indirizzo radice dell'API perché riferito alle API precedenti.
  2. Se l'app è stata creata tramite il portale di Azure classico, è necessario usare il nome della Risorsa applicazione, che è diverso dal nome dell'applicazione stessa. Se l'app è stata creata nel portale di Azure, è necessario usare il nome dell'applicazione stessa. In questo caso, il nome della Risorsa applicazione non differisce dal nome dell'app per le applicazioni create nel nuovo portale.