Questa documentazione è stata archiviata e non viene gestita.

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

Aggiornamento: giugno 2015

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

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

Questo argomento illustra i metodi per la richiesta di un token da ACS tramite il protocollo OAuth WRAP. Tutte le richieste di token tramite il protocollo OAuth WRAP vengono trasmesse tramite SSL. ACS emette sempre un Token Web semplice (SWT, Simple Web Token) tramite il protocollo OAuth WRAP in risposta a una richiesta di token formattata correttamente. Tutte le richieste di token tramite il protocollo OAuth WRAP vengono inviate a ACS in un POST HTTP. È possibile richiedere un token di ACS tramite il protocollo OAuth WRAP da qualsiasi piattaforma in grado di effettuare un POST FORM HTTPS: .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 la richiesta di un token SWT emesso da ACS tramite il protocollo OAuth WRAP.

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

Metodo di richiesta di token Descrizione

Richieste di token di password

Questo è il metodo più semplice e richiede al client di inviare un nome utente e una password da un'identità del servizio direttamente a ACS tramite il protocollo OAuth WRAP per l'autenticazione.

Richieste di token SWT

Questo metodo richiede al client di inviare un token SWT che può essere firmato con la chiave simmetrica di un'identità del servizio o con la chiave simmetrica del provider di identità ad ACS tramite il protocollo OAuth WRAP per l'autenticazione.

Richieste di token SAML

Destinato principalmente all'integrazione con Active Directory Federation Service (AD FS) 2.0, il metodo SAML (Security Assertion Markup Language) richiede al client di inviare un token SAML firmato ad ACS tramite il protocollo OAuth WRAP per l'autenticazione. Questo approccio permette al client di usare un'identità aziendale per l'autenticazione con ACS.

Tutte le richieste di token di ACS tramite il protocollo OAuth WRAP sono indirizzate a un endpoint emittente di token di ACS. L'URI di questo endpoint dipende dallo Spazi 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 Spazi dei nomi controllo di accesso denominato "mysnservice", sarà possibile indirizzare una richiesta di token all'URI seguente: https://mysnservice.accesscontrol.windows.net/WRAPv0.9.

Con una richiesta di token di password, un client può inviare un nome utente e una password da un'identità del servizio direttamente a ACS tramite il protocollo OAuth WRAP per l'autenticazione. Questo è il modo più semplice per richiedere un token da ACS usando il protocollo OAuth WRAP. 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:

 

Nome parametro Descrizione Requisiti relativi ai valori

wrap_scope

Verifica la corrispondenza della richiesta di token rispetto a un set di regole. Impostare il valore di questo parametro sul valore dell'area di autenticazione dell'applicazione relying party. È possibile ottenere questo valore (nel campo Area autenticazione) tramite il portale di gestione di ACS selezionando l'applicazione relying party appropriata dalla pagina Applicazioni relying party.

  • URI HTTP o HTTP(s)

  • Nessun parametro di query o ancoraggio.

  • Segmenti di tracciato <= 32.

  • Lunghezza massima: 256 caratteri.

  • Deve essere codificato con URL.

wrap_name

Convalida la chiave del parametro successivo. Impostare il valore di questo parametro sul nome di un'identità del servizio entro lo Spazi dei nomi controllo di accesso. È possibile ottenere questo valore (nel campo Nome) tramite il portale di gestione di ACS selezionando l'identità del servizio appropriata dalla pagina Identità del servizio.

  • Lunghezza minima: 1 carattere.

  • Lunghezza massima: 128 caratteri.

  • Deve essere codificato con URL.

wrap_password

Autentica la richiesta in arrivo. Impostare il valore di questo parametro sulla password di un'identità del servizio entro lo Spazi dei nomi controllo di accesso. È possibile ottenere questo valore (nel campo Password della pagina Modifica credenziali), tramite il portale di gestione di ACS selezionando prima di tutto l'identità del servizio appropriata nella pagina Identità del servizio e quindi selezionando la password appropriata nella tabella Credenziali della pagina Modifica identità del servizio.

  • Stringa con almeno 1 carattere e al massimo 64 caratteri di lunghezza.

  • Deve essere codificato con URL.

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

Le richieste di token di password tramite il protocollo OAuth WRAP possono anche contenere parametri aggiuntivi che possono essere usati da ACS durante il processo di calcolo delle attestazioni in uscita. 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 come inviarlo all'applicazione o al servizio Web, vedere Unwrapping and sending the token to a web application or service.

È anche possibile richiedere un token da ACS tramite il protocollo OAuth WRAP 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:

 

Nome parametro Descrizione Requisiti relativi ai valori

wrap_scope

Verifica la corrispondenza della richiesta di token rispetto a un set di regole.

  • Impostare il valore di questo parametro sul valore dell'area di autenticazione dell'applicazione relying party. È possibile ottenere questo valore (nel campo Area autenticazione) tramite il portale di gestione di ACS selezionando l'applicazione relying party appropriata dalla pagina Applicazioni relying party.

  • URI HTTP o HTTP(s).

  • Nessun parametro di query o ancoraggio.

  • Segmenti di tracciato <= 32.

  • Lunghezza massima: 256 caratteri.

  • Deve essere codificato con URL.

wrap_assertion

Questo è il token di input inviato a ACS.

  • Un token SWT formato con attestazioni in ingresso che includono i parametri Issuer e HMACSHA256.

  • Lunghezza massima: 2048 caratteri.

  • Deve essere codificato con URL.

wrap_assertion_format

Questo è il formato del token di input inviato a ACS.

SWT

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 o al servizio Web, vedere Unwrapping and sending the token to a web application or service.

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 Issuer e HMACSHA256, oltre a parametri aggiuntivi, ad esempio ExpiresOn, Audience e altre attestazioni specifiche del client. La tabella seguente include i nomi e le descrizioni dei parametri del token SWT:

 

Nome parametro Descrizione

Issuer

In ACS cerca la chiave usata per firmare il token. Se la firma è valida, questo valore verrà usato per eseguire il calcolo delle attestazioni in uscita.

È possibile impostare questo parametro sul valore dell'area di autenticazione di un provider di identità nello Spazi dei nomi controllo di accesso oppure sul nome di un'identità del servizio nello Spazi dei nomi controllo di accesso. È possibile ottenere questo valore (nel campo Area di autenticazione della pagina Modifica provider di identità) tramite il portale di gestione di ACS selezionando il provider di identità appropriato nella pagina Provider di identità. In alternativa, è possibile ottenere questo valore tramite il servizio di gestione ACS. Si tratta del nome della proprietà del record "Issuer" creato per ogni provider di identità.

HMACSHA256

In ACS convalida la firma SWT e cerca la chiave dell'autorità di certificazione indicata nel parametro Issuer.

La firma SWT viene creata usando la chiave di firma simmetrica associata a un'identità del servizio o a un provider di identità nello Spazi dei nomi controllo di accesso.

Audience

Se presente, ACS usa questo valore per verificare che ACS sia la destinazione prevista del token SWT. Si tratta dell'URL dello Spazi dei nomi controllo di accesso, ad esempio, https://contoso.accesscontrol.windows.net/

ExpiresOn

Se presente (in valore Epoch), indica se il token è scaduto. Ad esempio, il valore di questo parametro può essere 1324300962.

Attestazioni aggiuntive

Se presenti, ACS usa questi parametri per eseguire il calcolo delle attestazioni in uscita. Ogni tipo di attestazione deve essere presente solo una volta. Più valori di attestazione dello stesso tipo di attestazione devono essere concatenati tramite un carattere "," (virgola). Per altre informazioni sull'asserzione di attestazioni in ACS, vedere Asserzione di attestazioni tramite il protocollo OAuth WRAP.

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;
    }
}

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

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:

 

Nome parametro Descrizione Requisiti relativi ai valori

wrap_scope

Verifica la corrispondenza della richiesta di token rispetto a un set di regole.

  • Impostare il valore di questo parametro sul valore dell'area di autenticazione dell'applicazione relying party. È possibile ottenere questo valore (nel campo Area autenticazione) tramite il portale di gestione di ACS selezionando l'applicazione relying party appropriata dalla pagina Applicazioni relying party.

  • URI HTTP o HTTP(s).

  • Nessun parametro di query o ancoraggio.

  • Segmenti di tracciato <= 32.

  • Lunghezza massima: 256 caratteri.

  • Deve essere codificato con URL.

wrap_assertion

Questo è il token di input inviato a ACS.

  • Token SAML 1.1 o 2.0 firmato con attestazioni in ingresso. A causa di una limitazione, i token SAML 1.1 richiedono almeno un'attestazione in ingresso. È quindi necessario usare un provider di identità o un'identità del servizio abilitata per le attestazioni per l'autenticazione dei token SAML 1.1. I token SAML 2.0 non necessitano di attestazioni in ingresso per l'autenticazione rispetto a un'identità del servizio, oltre all'attestazione implicita NameIdentifier. È quindi possibile usare i token SAML 2.0 per l'autenticazione rispetto a un'identità del servizio normale non abilitata per le attestazioni.

  • Deve essere codificato con URL.

wrap_assertion_format

Questo è il formato del token di input inviato a ACS.

SAML

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 o al servizio Web, vedere Annullamento del wrapping e invio del token a un'applicazione o un servizio Web.

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

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 include le attestazioni da asserire e questo token viene firmato tramite una chiave del provider di identità archiviata in ACS. È ad esempio possibile inviare una richiesta di token SAML con attestazioni con asserzione a ACS tramite il protocollo OAuth WRAP da AD FS 2.0 o qualsiasi servizio token di sicurezza personalizzato creato tramite Windows Identity Foundation (WIF) e registrato in ACS come un provider di identità WS-Federation.

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

Se l'autenticazione della richiesta di token ha esito positivo, ACS restituirà 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 o al servizio Web, il client deve estrarlo e deve applicare al token la decodifica con URL 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));

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 includono anche SubCode e Detail, che forniscono contesto relativo agli errori. L'errore ha il formato seguente: Error:Code:<Statohttp>:Sub-Code:<codice>:Detail:<messaggio>. 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 di ACS.

Durante il debug o il ripristino da un errore restituito da ACS, è spesso necessario leggere il corpo della risposta. L'esempio di codice seguente mostra 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

Mostra: