Procedura: Richiedere un token da ACS tramite il protocollo OAuth WRAPPING

Si applica a

• Microsoft Azure Active Directory Access Control (anche noto come Servizio di controllo di accesso o ACS)

Panoramica

Quando le applicazioni Web e i servizi gestiscono l'autenticazione tramite ACS, il client deve ottenere un token di sicurezza rilasciato da ACS per accedere all'applicazione o al servizio. Per ottenere questo token emesso da ACS (token di output), il client deve eseguire l'autenticazione direttamente con ACS o inviare un token di sicurezza ACS rilasciato dal provider di identità (token di input). ACS convalida questo token di sicurezza di input, elabora le attestazioni di identità in questo token tramite il motore delle regole ACS, calcola le attestazioni di identità di output e rilascia un token di sicurezza di output.

Questo argomento descrive i metodi di richiesta di un token da ACS tramite il protocollo OAuth WRAPPING. Tutte le richieste di token tramite il protocollo OAuth WRAPPING vengono trasmesse tramite SSL. ACS genera sempre un token Web semplice (SWT) tramite il protocollo OAuth WRAPPING, in risposta a una richiesta di token formattata correttamente. Tutte le richieste di token tramite il protocollo OAuth WRAPPING vengono inviate a ACS in un POST HTTP. È possibile richiedere un token ACS tramite il protocollo OAuth WRAPPING da qualsiasi piattaforma in grado di creare un MODULO HTTPS POST: .NET Framework, Windows Communication Foundation (WCF), Silverlight, ASP.NET, Java, Python, Ruby, PHP, Flash e altre piattaforme.

Nella tabella seguente sono elencati tre metodi supportati per richiedere un token SWT rilasciato da ACS tramite il protocollo OAuth WRAPPING.

Tre metodi per la richiesta di un token da ACS tramite il protocollo OAuth WRAP

Endpoint emittente di token

Tutte le richieste di token ACS tramite il protocollo OAuth WRAPPING vengono indirizzate a un endpoint di emissione di token ACS. L'URI di questo endpoint dipende dallo spazio dei nomi Controllo di accesso. Lo spazio dei nomi viene visualizzato come prefisso del nome DNS in un URI di richiesta di token. Il resto del nome DNS è fisso, così come il percorso. Ad esempio, se si vuole richiedere un token dallo spazio dei nomi Controllo di accesso denominato "mysnservice", è possibile indirizzare una richiesta di token all'URI seguente: https://mysnservice.accesscontrol.windows.net/WRAPv0.9.

Richieste di token di password

Con una richiesta di token password, un client può inviare un nome utente e una password da un'identità del servizio direttamente a ACS tramite il protocollo OAuth WRAPPING per l'autenticazione. Questo è il modo più semplice per richiedere un token da ACS usando il protocollo OAuth WRAPPING. Oltre a stabilire una connessione SSL, questo approccio non richiede alcuna funzionalità di crittografia. In pratica è simile al modello nome utente/password prevalente nei servizi Web REST. Questo tipo di richiesta di token è in effetti un POST form HTTP. I parametri in una richiesta di token di password sono codificati come form.

Di seguito è riportato un esempio di una traccia di collegamento di una richiesta in testo normale per uno spazio dei nomi denominato "mysnservice".

POST /WRAPv0.9/ HTTP/1.1
Host: mysnservice.accesscontrol.windows.net
Content-Type: application/x-www-form-urlencoded

wrap_scope=http%3A%2F%2Fmysnservice.com%2Fservices%2F&
wrap_name=mysncustomer1&
wrap_password=5znwNTZDYC39dqhFOTDtnaikd1hiuRa4XaAj3Y9kJhQ%3D

La tabella seguente fornisce i nomi, le descrizioni e i requisiti relativi ai valori dei parametri la cui presenza è necessaria in una richiesta di token di password:

I valori di questi parametri devono essere codificati con URL prima di inviare la richiesta a ACS. L'applicazione Web o il servizio possono fornire il valore del wrap_scope al client oppure il client può decidere di impostare il valore del parametrowrap_scope sull'URI dell'applicazione Web o della destinazione risorsa del servizio.

Le richieste di token password tramite il protocollo OAuth WRAPPING possono contenere anche parametri aggiuntivi che possono essere usati da ACS durante il processo di calcolo delle attestazioni di output. I nomi e i valori dei parametri aggiuntivi devono essere codificati con URL e i valori non devono essere racchiusi tra virgolette.

Il metodo di richiesta di token di password è abbastanza semplice e usa .

WebClient client = new WebClient();
client.BaseAddress = string.Format("https://mysnservice.accesscontrol.windows.net");

NameValueCollection values = new NameValueCollection();
values.Add("wrap_name", "mysncustomer1");
values.Add("wrap_password", "5znwNTZDYC39dqhFOTDtnaikd1hiuRa4XaAj3Y9kJhQ=");
values.Add("wrap_scope", "http://mysnservice.com/services");

// WebClient takes care of the URL Encoding
byte[] responseBytes = client.UploadValues("WRAPv0.9", "POST", values);

// the raw response from ACS
string response = Encoding.UTF8.GetString(responseBytes);

Per informazioni su come decomprimere il token di output da ACS e inviarlo all'applicazione Web o al servizio, vedere Annullare l'applicazione e inviare il token a un'applicazione Web o un servizio.

Richieste di token SWT

È anche possibile richiedere un token da ACS tramite il protocollo OAuth WRAPPING usando un token SWT firmato da una chiave simmetrica. Tutte le richieste di token SWT vengono effettuate tramite un POST form HTTPS. I valori dei parametri in questo metodo di richiesta di token sono codificati come form.

Di seguito è riportato un esempio di traccia di collegamento di una richiesta di token SWT per lo spazio dei nomi "mysnservice".

POST /WRAPv0.9/ HTTP/1.1
Host: mysnservice.accesscontrol.windows.net
Content-Type: application/x-www-form-urlencoded

wrap_scope=http%3A%2F%2Fmysnservice.com%2Fservices%2F&
wrap_assertion_format=SWT&
wrap_assertion=Issuer%3dmysncustomer1%26HMACSHA256%3db%252f%252bJFwbngGdufECFjQb8qhb9YH0e32Cf9ABMDZFiPPA%253d

Una richiesta di token SWT deve avere i parametri e i valori seguenti:

Come illustrato nell'esempio seguente, il codice necessario per effettuare una richiesta di token SWT è simile al codice necessario per effettuare una richiesta di token di password.

WebClient client = new WebClient();
client.BaseAddress = string.Format("https://mysnservice.accesscontrol.windows.net");

NameValueCollection values = new NameValueCollection();
// add the wrap_scope
values.Add("wrap_scope", "http://mysnservice.com/services");
// add the format
values.Add("wrap_assertion_format", "SWT");
// add the SWT
values.Add("wrap_assertion", "Issuer=mysncustomer1&HMACSHA256=b%2f%2bJFwbngGdufECFjQb8qhb9YH0e32Cf9ABMDZFiPPA%3d");
// WebClient takes care of the remaining URL Encoding
byte[] responseBytes = client.UploadValues("WRAPv0.9", "POST", values);

// the raw response from ACS
string response = Encoding.UTF8.GetString(responseBytes);

Per informazioni su come decomprimere la risposta da ACS e inviarla all'applicazione Web o al servizio, vedere Annullare l'applicazione e inviare il token a un'applicazione Web o a un servizio.

Creazione di un token SWT

Un token SWT è un insieme di coppie chiave/valore firmate con una chiave dell'autorità di certificazione (una chiave simmetrica). Un token SWT inviato a ACS in una richiesta di token SWT deve contenere i parametri Emittente e HMACSHA256, nonché parametri aggiuntivi, ad esempio Scadenza, Audience e altre attestazioni specifiche del client. La tabella seguente include i nomi e le descrizioni dei parametri del token SWT:

L'esempio di codice seguente mostra come generare un token SWT usando . Contiene un tipo che crea token SWT che includono i parametri Issuer e HMACSHA256.

using System;
using System.Collections.Generic;
using System.Linq;
using System.Security.Cryptography;
using System.Text;
using System.Web;

public class TokenFactory
{
    string signingKey;   
    string issuer;
    
    public TokenFactory(string issuer, string signingKey)
    {
        this.issuer = issuer;
        this.signingKey = signingKey;
    }

    public string CreateToken()
    {
        StringBuilder builder = new StringBuilder();

        // add the issuer name
        builder.Append("Issuer=");
        builder.Append(HttpUtility.UrlEncode(this.issuer));

        string signature = this.GenerateSignature(builder.ToString(), this.signingKey);
        builder.Append("&HMACSHA256=");
        builder.Append(signature);

        return builder.ToString();
    }

   
    private string GenerateSignature(string unsignedToken, string signingKey)
    {
        HMACSHA256 hmac = new HMACSHA256(Convert.FromBase64String(signingKey));

        byte[] locallyGeneratedSignatureInBytes = hmac.ComputeHash(Encoding.ASCII.GetBytes(unsignedToken));

        string locallyGeneratedSignature = HttpUtility.UrlEncode(Convert.ToBase64String(locallyGeneratedSignatureInBytes));

        return locallyGeneratedSignature;
    }
}

Richieste di token SAML

Il metodo di richiesta del token SAML è destinato principalmente all'integrazione di AD FS 2.0 e consente al client di usare un'identità aziendale (Active Directory) per l'autenticazione con ACS. Con il metodo di richiesta del token SAML, è possibile inviare un token SAML 1.1 firmato o un token SAML 2.0 rilasciato da AD FS 2.0 (token di input) a ACS tramite il protocollo OAuth WRAPPING.

ACS usa le regole corrispondenti per calcolare le attestazioni in uscita, le raggruppa in un token SWT (token di output), lo firma e lo restituisce al client tramite il protocollo OAuth WRAP.

Una richiesta di token SAML deve avere i parametri e i valori seguenti:

Di seguito è riportato un esempio del codice necessario per effettuare una richiesta di token SAML.

private static string SendSAMLTokenToACS(string samlToken)
{
 try
 {
  WebClient client = new WebClient();
  client.BaseAddress = string.Format("https://mysnservice.accesscontrol.windows.net");
  NameValueCollection parameters = new NameValueCollection();
  parameters.Add("wrap_assertion_format", "SAML");
  parameters.Add("wrap_assertion", samlToken);
  parameters.Add("wrap_scope", "http://mysnservice.com/services");

  byte[] responseBytes = client.UploadValues("WRAPv0.9", parameters);
  string response = Encoding.UTF8.GetString(responseBytes);

  return response
   .Split('&')
   .Single(value => value.StartsWith("wrap_access_token=", StringComparison.OrdinalIgnoreCase))
   .Split('=')[1];
 }
 catch (WebException wex)
 {
  string value = new StreamReader(wex.Response.GetResponseStream()).ReadToEnd();
  throw;
 }
}  

Per informazioni su come decomprimere la risposta da ACS e inviarla all'applicazione Web o al servizio, vedere Annullare l'applicazione e inviare il token a un'applicazione Web o a un servizio.

Asserzione di attestazioni tramite il protocollo OAuth WRAP

Per abilitare la compatibilità con le versioni precedenti con il comportamento della richiesta del token ACS 1.0, ACS supporta la possibilità di affermare le attestazioni come parte delle richieste di token.

Registrare l'applicazione o il servizio che effettua l'asserzione come provider di identità ACS.

Per ottenere questo risultato, è consigliabile registrare l'applicazione o il servizio che effettua l'asserzione come provider di identità ACS. L'applicazione o il servizio richiede quindi un token da ACS presentando un token SAML o SWT che contiene le attestazioni che vuole asserire e questo token viene firmato usando una chiave del provider di identità archiviata in ACS. Ad esempio, è possibile inviare una richiesta di token SAML con attestazioni asserte a ACS tramite il protocollo OAuth WRAPPING da AD FS 2.0 o qualsiasi servizio token di sicurezza personalizzato creato usando Windows Identity Foundation (WIF) e registrato in ACS come provider di identità WS-Federation.

È possibile usare il portale di gestione di ACS per registrare un provider di identità usando i metadati WS-Federation oppure è possibile usare il servizio di gestione ACS per impostare singolarmente le proprietà del provider di identità, gli indirizzi e le chiavi. Ad esempio, vedere Procedura: Usare il servizio di gestione ACS per configurare AD FS 2.0 come Enterprise provider di identità. Nessuna identità del servizio è necessaria in questo metodo di asserzione di attestazioni in una richiesta di token. Questo metodo è funzionale tramite tutti i protocolli supportati da ACS.

Annullamento del wrapping e invio del token a un'applicazione o un servizio Web

Se la richiesta del token viene autenticata correttamente, ACS restituisce due parametri con codifica form: wrap_token e wrap_token_expires_in. I valori di questi parametri corrispondono rispettivamente al token SWT effettivo che il client può usare per ottenere l'accesso all'applicazione o al servizio Web e alla durata approssimativa rimanente di questo token (in secondi).

Prima di inviare il token SWT all'applicazione Web o al servizio, il client deve estrarre e decodificarlo dalla risposta ACS. Se l'applicazione o il servizio Web richiede che il token sia presentato nell'intestazione Authorization HTTP, il token dovrà essere preceduto dallo schema WRAPv0.9.

L'esempio di codice seguente illustra come decomprimere un token e come formattare l'intestazione Authorization.

WebClient client = new WebClient();
client.BaseAddress = string.Format("https://mysnservice.accesscontrol.windows.net");

NameValueCollection values = new NameValueCollection();
values.Add("wrap_name", "mysncustomer1");
values.Add("wrap_password", "5znwNTZDYC39dqhFOTDtnaikd1hiuRa4XaAj3Y9kJhQ=");
values.Add("wrap_scope", "http://mysnservice.com/services");

// WebClient takes care of the URL Encoding
byte[] responseBytes = client.UploadValues("WRAPv0.9", "POST", values);

// the raw response from ACS
string response = Encoding.UTF8.GetString(responseBytes);

string token = response
    .Split('&')
    .Single(value => value.StartsWith("wrap_token=", StringComparison.OrdinalIgnoreCase))
    .Split('=')[1];

string.Format("WRAP access_token=\"{0}\"", HttpUtility.UrlDecode(token));

Codici di errore ACS e relative descrizioni

ACS restituisce errori quando non riesce a soddisfare una richiesta di token. In conformità con la progettazione REST, l'errore contiene un codice di risposta HTTP. In molti casi, gli errori ACS contengono anche un SubCode oggetto e Detail che forniscono un contesto relativo a ciò che non è riuscito. Il formato di errore è: Error:Code:httpStatus:Sub-Code:<code>:D etail<:<message>.> Il valore Content-Type di un errore è sempre text/plain.

HTTP/1.1 401 Access Forbidden
Content-Type: text/plain; charset=us-ascii

Error:Code:401:SubCode:T0:Detail:ACS50009: SWT token is invalid. :TraceID:<trace id value>:TimeStamp:<timestamp value>

Per altre informazioni sui codici di errore ACS, vedere Codici di errore ACS.

Quando si esegue il debug o il ripristino da un errore restituito da ACS, è spesso necessario leggere il corpo della risposta. Nell'esempio di codice seguente viene illustrato come leggere il messaggio di errore da un oggetto WebException .

try
{
    WebClient client = new WebClient();
    client.BaseAddress = string.Format("https://mysnservice.accesscontrol.windows.net");

    NameValueCollection values = new NameValueCollection();
    values.Add("wrap_name", "mysncustomer1");
    values.Add("wrap_password", "5znwNTZDYC39dqhFOTDtnaikd1hiuRa4XaAj3Y9kJhQ=");
    values.Add("wrap_scope", "http://mysnservice.com/services");

    // WebClient takes care of the URL Encoding
    byte[] responseBytes = client.UploadValues("WRAPv0.9", "POST", values);

    // the raw response from ACS
    string response = Encoding.UTF8.GetString(responseBytes);

    string token = response
        .Split('&')
        .Single(value => value.StartsWith("wrap_access_token=",       StringComparison.OrdinalIgnoreCase))
        .Split('=')[1];
}
catch (WebException wex)
{
    if (wex.Response != null)
    {
        // the response Stream contains the error message
        StreamReader reader = new StreamReader(wex.Response.GetResponseStream());
        string message = reader.ReadToEnd();
    }
    // Throw as appropriate
}

Vedere anche

Concetti

Procedure di ACS