VENDITE: 1-800-867-1389

Implementare OAuth nell'applicazione per Marketplace

Aggiornamento: gennaio 2014

 

 

Questo argomento è stato originariamente pubblicato con il titolo "Utilizzare OAuth nell'applicazione per DataMarket".

Gli sviluppatori possono creare e vendere le applicazioni create in Marketplace. Queste applicazioni possono utilizzare dati di Marketplace, nel qual caso per poter utilizzare dati di un'origine esterna l'utente deve effettuare la sottoscrizione al set di dati.

 

Sezione Descrizione

Flussi di consenso dell'utente

Vengono descritti i processi in base a cui l'utente fornisce o nega il consenso per l'accesso da parte di un'applicazione a risorse protette in Marketplace.

Flusso di consenso per applicazioni Web ASP.NET con l'estensione Windows Identity Foundation per OAuth

Viene descritto come ottenere il consenso da un utente in un'applicazione ASP.NET con Marketplace mediante OAuth. Sono disponibili esempi di codice.

Flusso di consenso per applicazioni Web

Viene descritto come ottenere il consenso da un utente in qualsiasi applicazione Web con Marketplace mediante OAuth. Sono disponibili esempi di codice.

Eseguire l'autenticazione ai servizi di Marketplace mediante OAuth

Viene descritto come accedere ai servizi di Marketplace per conto di un utente quando si utilizza OAuth.

Utilizzare il token di aggiornamento per ottenere un nuovo token di accesso OAuth

Viene descritto come gestire la scadenza di un token di accesso OAuth utilizzando il token di aggiornamento per ottenerne uno nuovo.

Tipi di richieste di autorizzazione

Vengono descritti i diversi tipi di richieste di autorizzazione che è possibile utilizzare per accedere ai servizi di Marketplace.

Registrare un'applicazione

Vengono fornite le istruzioni necessarie per registrare in Marketplace un'applicazione che utilizza OAuth.

Appendice

Tabelle di Parametri, Matrice dei parametri x_permissions e x_required_offers e Messaggi di errore.

Affinché un'applicazione possa accedere a Marketplace per conto di un utente, l'utente deve fornire il consenso per l'accesso dell'applicazione ai relativi account e sottoscrizioni. Il processo mediante cui un utente fornisce tale consenso è denominato flusso di consenso dell'utente OAuth.

Il flusso di consenso può prevedere varie fasi in base allo stato dell'account dell'utente e alle opzioni di consenso richieste dall'applicazione.

Se l'utente fornisce il consenso, l'applicazione ottiene un token di accesso che verrà utilizzato per eseguire l'autenticazione con i servizi di Marketplace per conto dell'utente.

Nelle sottosezioni che seguono viene descritto come integrare il flusso di consenso OAuth nell'applicazione in base all'architettura.

L'estensione Windows Identity Foundation (WIF) per OAuth semplifica l'integrazione con Marketplace mediante OAuth. Questa libreria implementa il protocollo OAuth 2.0 ed espone semplici metodi per la gestione del flusso di consenso dell'utente.

noteNota
L'estensione Windows Identity Foundation (WIF) per OAuth è una versione Community Technology Preview (CTP) non supportata da Microsoft.

  • Scaricare e installare il runtime Windows Identity Foundation.

  • Scaricare e installare l'estensione Windows Identity Foundation (WIF) per OAuth.

  • Aggiungere nel progetto un riferimento ai due assembly seguenti:

    • Microsoft.IdentityModel.Protocols.OAuth
      Questo assembly si trova nella directory di destinazione in cui è stata decompressa l'estensione Windows Identity Foundation (WIF) per OAuth.

    • System.IdentityModel
      Questo assembly si trova nella directory di installazione del runtime .NET.

Per avviare il flusso di consenso, è possibile chiamare il metodo statico RedirectToEndUserEndpoint() nella classe OAuthClient. La richiesta HTTP corrente risponderà con un reindirizzamento HTTP 302 al flusso di consenso di Marketplace.

Il terzo parametro nell'esempio di codice riportato di seguito è l'URL a cui viene reindirizzato il browser dell'utente al termine del flusso di consenso. Questo valore deve corrispondere all'URI di reindirizzamento specificato durante la registrazione dell'applicazione in Marketplace.


OAuthClient.RedirectToEndUserEndpoint(
              "https://datamarket.azure.com",
              AuthorizationResponseType.Code,
              "http://myapp.com/authcomplete");

Al termine del flusso di consenso o in caso di errore, il browser dell'utente viene reindirizzato all'applicazione nell'URI specificato in precedenza. L'estensione WIF per OAuth riceve ed elabora il reindirizzamento e chiama un gestore di eventi registrato.

Affinché l'estensione WIF per OAuth possa elaborare il reindirizzamento, è necessario registrare il gestore della libreria client aggiungendo quanto segue al file Web.config dell'applicazione ASP.NET o creando un nuovo file.


<system.webServer>
   <handlers>
      <add name="DataMarketOAuthHandler" 
           verb="*" 
           path="DataMarketOAuthHandler.ashx"
           type="Microsoft.IdentityModel.Protocols.OAuth.Client.EndUserAuthorizationResponseHandler, 
                 Microsoft.IdentityModel.Protocols.OAuth" />
   </handlers>
</system.webServer>

È possibile scegliere valori personalizzati per gli attributi relativi al nome e al percorso. L'URL assoluto è costituito dall'URL di base dell'applicazione concatenato con l'attributo del percorso del metodo OAuthClient.RedirectToEndUserEndpoint(). L'URL assoluto deve corrispondere a quello specificato durante la registrazione dell'applicazione in Marketplace.

È inoltre necessario implementare gestori di eventi per la ricezione dei token di accesso e di aggiornamento OAuth 2.0 o per la gestione di un eventuale errore del flusso di consenso. I metodi implementati devono corrispondere alle firme riportate di seguito.


public void OAuthClientSettings.AccessTokenReceived(
                      object Sender,
                      AccessTokenReceivedEventArgs tokenReceivedEventArgs);

Void OAuthClientSettings.EndUserAuthorizationFailed(
                      object Sender,
                      EndUserAuthorizationFailedEventArgs authorizationFailedEventArgs);

Nel gestore AccessTokenReceived è possibile ottenere il token di accesso in tokenReceivedEventArgs.AuthorizationResponse.Parameters[OAuthConstants.AccessToken] e il token di aggiornamento in tokenReceivedEventArgs.AuthorizationResonse.Parameters[OAuthConstants.RefreshToken].

Aggiungere all'applicazione il codice riportato di seguito per configurare l'estensione WIF per OAuth con le impostazioni OAuth per Marketplace. Questo codice può essere aggiunto al metodo Application_Start della classe HttpApplication ASP.NET.

Sostituire i segnaposti del codice con i valori relativi a ID client e segreto client ottenuti durante la registrazione dell'applicazione. Sostituire inoltre AccessTokenReceived ed EndUserAuthorizationFailed con i nomi dei gestori di eventi descritti nella sezione precedente.


// set up the ServerRegistry
InMemoryAuthorizationServerRegistery serverRegistry = 
               new InMemoryAuthorizationServerRegistry(); 
AuthorizationsServerRegistration registrationInfo = 
               new AuthorizationServerRegistration(                                   "https://datamarket.accesscontrol.windows.net/v2/OAuth2-13",
                                   "https://datamarket.azure.com/embedded/consent", 
                                   <<Your OAuth Client ID>>, 
                                   <<Your OAuth Client Secret>>>);

serverRegistry.AddOrUpdate(registrationInfo);
OAuthClientSettings.AuthorizationServerRegistry = serverRegistry; 

// set up the ResourceRegistry 
InMemoryResourceScopeMappingRegistry resourceRegistry = 
               new InMemoryResourceScopeMappingRegistry(); 

resourceRegistry.AddOrUpdate(
                             "https://datamarket.azure.com/embedded/consent", 
                             "https://datamarket.accesscontrol.windows.net/v2/OAuth2-13”, 
                             "https://datamarket.azure.com/embedded/consent", 
                             new string[] { "" }); 
OAuthClientSettings.ResourceScopeMappingRegistry = resourceRegistry; 

// handle the token received event 
OAuthClientSettings.AccessTokenreceived += 
                       new EventHandler<AccessTokenReceivedEventArgs>(OAuthClientSettings_AccessTokenReceived);  

// handle the event when the user denies consent 
OAuthClientSettings.EndUerAuthorizationFailed += 
                       new EventHandler<EndUserAuthorizationFailedEventArgs>(OAuthClientSettings_EndUserAuthorizaitonFailed);  

// register the Authentication Module
AuthenticationManager.Register(new OAuthAuthenticationModule());

In questa sezione viene descritto come integrare l'applicazione Web con il flusso di consenso OAuth 2.0 per Marketplace. Se l'applicazione Web viene implementata mediante ASP.NET, valutare se utilizzare l'estensione Windows Identity Foundation (WIF) per OAuth come descritto nella sezione precedente.

Per avviare il flusso di consenso, un'applicazione Web reindirizza il browser dell'utente all'URL di consenso di Marketplace. L'utente completa quindi le varie fasi del flusso di consenso nella finestra del browser. Al termine, il browser dell'utente verrà reindirizzato da Marketplace all'URL di reindirizzamento post-consenso dell'applicazione.

Per avviare il flusso di consenso, reindirizzare il browser dell'utente all'URL di consenso di Marketplace. Questo URL viene creato a partire dall'URL di base e dai parametri della stringa di query.

L'URL di base è https://datamarket.azure.com/embedded/consent.

L'URL del flusso di consenso supporta i parametri della stringa di query riportati di seguito.

 

Parametro Obbligatorio/Facoltativo Descrizione

client_id

Obbligatorio

L'ID client registrato in Marketplace.

redirect_uri

Facoltativo

L'URI a cui viene reindirizzato il browser dell'utente al termine del flusso di consenso.

Se questo parametro viene specificato, il sistema verifica che corrisponda all'URI di reindirizzamento registrato in precedenza per il client. I due URI corrispondono se tutti i componenti sono uguali tranne la stringa di query.

Il valore di questo parametro deve essere codificato come URL.

response_type

Obbligatorio

Il meccanismo che verrà utilizzato per restituire un token di accesso all'applicazione richiedente. È supportato solo il valore code.

state

Facoltativo

È possibile utilizzare questo parametro per passare dati arbitrari dall'inizio alla fine del flusso di consenso. Qualsiasi valore incluso per tale parametro verrà aggiunto al parametro della stringa di query dell'ambito quando il browser dell'utente viene reindirizzato all'URI di reindirizzamento al termine del flusso di consenso.

x_permissions

Facoltativo

Questo parametro determina le autorizzazioni di cui disporrà l'applicazione per l'account di Azure Marketplace dell'utente. Tale parametro può contenere l'account o un identificatore di offerta. Con un account, l'applicazione potrà accedere all'intero account di Azure Marketplace dell'utente, incluse tutte le sottoscrizioni correnti e future. Con un identificatore di offerta, l'applicazione potrà accedere solo alle sottoscrizioni relative all'offerta specificata.

È possibile specificare gli identificatori di offerta come elenco delimitato da spazi. Ciascun identificatore corrisponde ai nomi del provider e dell'offerta ricavati dall'URL radice del servizio nella pagina dei dettagli del set di dati di tale offerta. Per richiedere ad esempio l'accesso al set di dati Data.gov Crime, è possibile costruire il parametro x_permissions nel seguente modo:

  1. Esaminare la pagina dei dettagli del set di dati relativa all'offerta.

  2. Nella scheda Dettagli individuare l'URL radice del servizio. Per l'offerta corrente, si tratta di https://api.datamarket.azure.com/data.gov/Crimes/.

  3. Costruire l'identificatore di offerta utilizzando le parti dell'URL relative al provider e all'offerta. Per l'offerta corrente, si tratta di data.gov/Crimes.

  4. Impostare x_permissions=data.gov/Crimes.

Se sono specificati uno o più identificatori di offerta, l'ambito di tutti i token di accesso risultanti dalla concessione del consenso viene limitato in modo da consentire l'accesso alle sole offerte specificate.

Se è specificata la parola account, tutti i token di accesso risultanti dalla concessione del consenso hanno accesso a tutte le offerte correnti e future.

x_required_offers

Facoltativo

Questo parametro richiede che l'utente abbia effettuato una sottoscrizione all'offerta specificata. Al'utente che non dispone ancora di una sottoscrizione attiva verrà chiesto di effettuare la sottoscrizione durante il flusso di consenso.

Il formato dell'identificatore di offerta utilizzato in questo parametro è identico a quello del parametro x_permissions definito in precedenza.

Se questo parametro è specificato, x_permissions viene impostato automaticamente sullo stesso identificatore di offerta e non può essere impostato nella stringa di query.

x_scope

Facoltativo

Il form codificato come URL dell'endpoint che ospita il servizio dati a cui si accederà. Se non specificato, il valore predefinito è https://api.datamarket.azure.com/.

Se ad esempio si accede al servizio dati disponibile all'indirizzo https://api.datamarket.azure.com/data.gov/crimes, il valore dell'ambito sarà https://api.datamarket.azure.com/.

Analogamente, se si accede al servizio dati disponibile all'indirizzo http://api.microsofttranslator.com, il valore dell'ambito sarà http://api.microsofttranslator.com/.

L'URL di consenso riportato di seguito richiede ad esempio l'accesso all'intero account di un utente.

Le interruzioni di riga servono unicamente per motivi di leggibilità e non devono essere incluse nel codice.


https://datamarket.azure.com/embedded/consent?
client_id=myapp&
response_type=code&
x_permissions=account

L'URL di consenso riportato di seguito richiede ad esempio l'accesso all'intero account di un utente che disponga di una sottoscrizione attiva al set di dati Data.gov Crime.

Le interruzioni di riga servono unicamente per motivi di leggibilità e non devono essere incluse nel codice.


https://datamarket.azure.com/embedded/consent?
client_id=myapp&
response_type=code&
x_required_offers=data.gov/Crimes

L'esempio riportato di seguito richiede che l'utente disponga di una sottoscrizione attiva a Microsoft Translator e consente l'accesso all'endpoint SOAP all'indirizzo http://api.microsofttranslator.com/V2/Soap.svc.

Le interruzioni di riga servono unicamente per motivi di leggibilità e non devono essere incluse nel codice.


https://datamarket.azure.com/embedded/consent?
client_id=myapp&
response_type=code&
x_required_offers= Bing/MicrosoftTranslator&
x_scope=http%3a%2f%2fapi.microsofttranslator.com%2f
0

Dopo che l'applicazione ha creato un URL di consenso di Marketplace, è possibile reindirizzare il browser dell'utente a questo URL utilizzando un reindirizzamento HTTP 302 oppure aprendo una nuova sessione del browser.

Al termine del flusso di consenso o in caso di errore, il browser dell'utente viene reindirizzato all'URL di reindirizzamento post-consenso dell'applicazione.

Se il flusso di consenso è stato completato in modo corretto, l'URL di reindirizzamento post-consenso conterrà un parametro della stringa di query denominato code contenente il codice di autorizzazione restituito da Marketplace. È possibile scambiare questo codice con un token di accesso e un token di aggiornamento da utilizzare per l'autenticazione con i servizi di Marketplace.

Se il flusso di consenso non è stato completato in modo corretto, l'URL di reindirizzamento post-consenso conterrà i parametri della stringa di query riportati di seguito.

 

Parametro Descrizione

error

Uno dei codici di errore seguenti:

  • invalid_request
    La richiesta non contiene un parametro obbligatorio, include un parametro o un valore di parametro non supportato oppure è in un formato non corretto.

  • unauthorized_client
    Il client non è autorizzato a richiedere un codice di autorizzazione con questo metodo.

  • access_denied
    Il proprietario della risorsa o il server di autorizzazione ha negato la richiesta.

  • unsupported_response_type
    Il server di autorizzazione non supporta il rilascio di un codice di autorizzazione con questo metodo.

  • invalid_scope
    L'ambito richiesto non è valido, non è noto oppure è in un formato non corretto.

error_description

Un testo leggibile che fornisce informazioni aggiuntive, utilizzate per l'analisi e la risoluzione dell'errore che si è verificato.

state

Se è presente, corrisponde al parametro "state" della richiesta di consenso originale. Deve essere impostato sul valore esatto ricevuto dall'applicazione.

Per scambiare il codice di autorizzazione con un token di accesso e un token di aggiornamento, inviare una richiesta POST HTTP all'endpoint del token OAuth 2.0 per Marketplace (https://datamarket.accesscontrol.windows.net/v2/OAuth2-13).

Nel corpo della richiesta HTTP inviata all'endpoint devono essere presenti diversi parametri. Il contenuto del corpo della richiesta deve essere di tipo application/x-www-form-urlencoded.

 

Parametro Obbligatorio/Facoltativo Valore

client_id

Obbligatorio

L'ID client dell'applicazione registrata in Marketplace. Il parametro client_id deve corrispondere all'ID client passato all'URL di consenso di Marketplace affinché il flusso di consenso venga avviato e deve essere nel formato codificato come URL.

client_secret

Obbligatorio

Il segreto client dell'applicazione registrata in Marketplace. Il parametro client_secret deve essere nel formato codificato come URL.

code

Obbligatorio

Il codice di autorizzazione ricevuto nell'URL di reindirizzamento post-consenso. Il parametro code deve essere nel formato codificato come URL.

grant_type

Obbligatorio

Deve essere impostato su authorization_code.

redirect_uri

Obbligatorio

L'URI di reindirizzamento specificato durante la registrazione dell'applicazione. Il parametro redirect_uri deve essere nel formato codificato come URL.

scope

Obbligatorio

Il form codificato come URL dell'endpoint che ospita il servizio dati a cui si accederà. Deve corrispondere al valore dell'ambito specificato quando si richiama il flusso di consenso.

Se ad esempio si accede al servizio dati disponibile all'indirizzo https://api.datamarket.azure.com/data.gov/crimes, il valore dell'ambito sarà https://api.datamarket.azure.com/.

Analogamente, se si accede al servizio dati disponibile all'indirizzo http://api.microsofttranslator.com, il valore dell'ambito sarà http://api.microsofttranslator.com/.

Di seguito è riportato un esempio della richiesta inviata all'endpoint del token per lo scambio di un codice di autorizzazione.

noteNota
Le interruzioni di riga nel corpo della richiesta HTTP servono unicamente per motivi di leggibilità e devono essere rimosse.


Post /v2/OAuth2-13 HTTP/1.1
Host: datamarket.accesscontrol.windows.net
Content-Type: application/x-www-form-urlencoded

code=1235486542&
client_id=myapp&
client_secret=MzX8SVXpgjOQWODwZfqiUGfp0FvGPZ&
redirect_uri=https%3a%2f%2fmyapp.com%2fauthcomplete&
grant_type=authorization_code&
scope=https%3a%2f%2fapi.datamarket.azure.com%2f

Il token di accesso ricevuto è codificato in un oggetto JSON.


HTTP/1.1 200 OK
Cache-Control: public, no-store, max-age=0
Content-Type: application/json; charset=us-ascii
Expires: Wed, 20 Apr 2011 18:48:53 GMT
Last-Modified: Wed, 20 Apr 2011 18:48:53 GMT
Vary: *
Server: Microsoft-IIS/7.0
Set-Cookie: ASP.NET_SessionId=chqpl445frmvsaeozn45bu55; path=/; HttpOnly
X-AspNetMvc-Version: 2.0
X-AspNet-Version: 2.0.50727
X-Powered-By: ASP.NET
Date: Wed, 20 Apr 2011 18:48:53 GMT
Content-Length: 883

{"access_token":"http%3a%2f%2fschemas.xmlsoap.org%2fws%2f2005%2f05%2fidentity%2fclaims%2fnameidentifier=812d5dea-1111-43c0-b2af-38cbe4d58bf8&http%3a%2f%2fschemas.microsoft.com%2faccesscontrolservice%2f2010%2f07%2fclaims%2fpermissions=10a6465f-b0a6-49ca-9175-b24caaf74db0&http%3a%2f%2fschemas.xmlsoap.org%2fws%2f2009%2f09%2fidentity%2fclaims%2factor=myapp&http%3a%2f%2fschemas.microsoft.com%2faccesscontrolservice%2f2010%2f07%2fclaims%2fidentityprovider=DataMarketIdentityProvider&Audience=https%3a%2f%2fapi.datamarket.azure.com&ExpiresOn=1303325933&Issuer=https%3a%2f%2fdatamarket.accesscontrol.windows.net%2f&HMACSHA256=YWSfH6Byumh7HqI4j7U8dsXFD88f42irvNVtGdG8zCY%3d",
"token_type":"http://schemas.xmlsoap.org/ws/2009/11/swt-token-profile-1.0",
"expires_in":"599",
"refresh_token":"uG/QvG8eKagO5NFM2XcnSQ==","scope":
"https://api.datamarket.azure.com/"}

Tutti i servizi di Marketplace ora supportano OAuth come metodo di autenticazione. Quando si esegue l'autenticazione utilizzando OAuth, è necessario specificare un token di accesso valido nell'intestazione di autorizzazione della richiesta. Il valore dell'intestazione di autorizzazione deve contenere be "Bearer " + e il token di accesso.

Di seguito è riportata una richiesta di esempio con un token di accesso OAuth.


GET /Data.ashx/WeatherBug/HistoricalObservations/HistHilo?$filter=Station_ID%20eq%20'46005' HTTP/1.1
Host: api.datamarket.azure.com
Connection: keep-alive
Authorization: Bearer http%3a%2f%2fschemas.xmlsoap.org%2fws%2f2005%2f05%2fidentity%2fclaims%2fnameidentifier=812d5dea-1111-43c0-b2af-38cbe4d58bf8&http%3a%2f%2fschemas.microsoft.com%2faccesscontrolservice%2f2010%2f07%2fclaims%2fpermissions=10a6465f-b0a6-49ca-9175-b24caaf74db0&http%3a%2f%2fschemas.xmlsoap.org%2fws%2f2009%2f09%2fidentity%2fclaims%2factor=myapp&http%3a%2f%2fschemas.microsoft.com%2faccesscontrolservice%2f2010%2f07%2fclaims%2fidentityprovider=DataMarketIdentityProvider&Audience=https%3a%2f%2fapi.datamarket.azure.com&ExpiresOn=1303325933&Issuer=https%3a%2f%2fdatamarket.accesscontrol.windows.net%2f&HMACSHA256=YWSfH6Byumh7HqI4j7U8dsXFD88f42irvNVtGdG8zCY%3d
User-Agent: Mozilla/5.0 (Windows; U; Windows NT 6.1; en-US) AppleWebKit/534.16 (KHTML, like Gecko) Chrome/10.0.648.204 Safari/534.16
Accept: application/atomsvc+xml;q=0.8, application/json;q=0.5, */*;q=0.1
Accept-Encoding: gzip,deflate,sdch
Accept-Language: en-US,en;q=0.8
Accept-Charset: ISO-8859-1,utf-8;q=0.7,*;q=0.3

Se si utilizzano le funzionalità JSON/P, è inoltre possibile includere il token di accesso nel parametro della stringa di query accessToken con il prefisso "Bearer ". Per ulteriori informazioni sul supporto JSON/P, vedere l'argomento JSON/P support for Marketplace services.


<html>
<body>

<script type="text/javascript">
function ondataready(data) {
alert(data);
}
</script>

<script type="text/javascript" src="https://api.datamarket.azure.com/UnitedNations/Demographic/DataSeries?
$callback=ondataready&$format=json&accesstoken=Bearer%20http%253a%252f%252fschemas.xmlsoap.org%252fws
%252f2005%252f05%252fidentity%252fclaims%252fnameidentifier%3dbac9e6aa-3e22-4e05-87da-0525283708de%26http%253a%252f
%252fschemas.microsoft.com%252faccesscontrolservice%252f2010%252f07%252fclaims%252fpermissions%3daccount%26http%253a%252f
%252fschemas.xmlsoap.org%252fws%252f2009%252f09%252fidentity%252fclaims%252factor%3dembedded_demo%26http%253a%252f
%252fschemas.microsoft.com%252faccesscontrolservice%252f2010%252f07%252fclaims%252fidentityprovider
%3dDataMarketIdentityProvider%26Audience%3dhttps%253a%252f%252fapi.datamarket.azure.com%252f%26ExpiresOn
%3d1329153508%26Issuer%3dhttps%253a%252f%252fdatamarket.accesscontrol.windows.net%252f
%26HMACSHA256%3dcPBhxF7iLAy4mSQ98D8NYyrthl2QxqLu0aqHuxlCBOU%253d"></script>

</body>
</html>

Poiché i token di accesso sono validi solo per 10 minuti, se l'applicazione prevede di accedere all'account dell'utente per un periodo di tempo maggiore, è necessario gestire l'aggiornamento del token.

Per informazioni dettagliate su come eseguire l'aggiornamento di un token di accesso, vedere la sezione 6 della specifica OAuth 2.0. Si noti che per l'aggiornamento viene utilizzato lo stesso endpoint del token utilizzato per lo scambio del codice di autenticazione con un token di accesso e che nella richiesta di aggiornamento è necessario specificare scope=https%3a%2f%2fapi.datamarket.azure.com%2f.

Di seguito è riportata una richiesta di esempio relativa a un nuovo token di accesso.

noteNota
Le interruzioni di riga nel corpo della richiesta HTTP servono unicamente per motivi di leggibilità e devono essere rimosse.


Post /v2/OAuth2-13 HTTP/1.1
Host: datamarket.accesscontrol.windows.net
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&
client_id=myapp&
client_secret=mysecret&
refresh_token=uG%2fQvG8eKagO5NFM2XcnSQ%3d%3d&
scope=https%3a%2f%2fapi.datamarket.azure.com%2f

Dopo che l'utente ha eseguito l'accesso con l'account di Marketplace, l'applicazione può richiedere l'accesso a tutti i set di dati a cui l'utente ha effettuato la sottoscrizione oppure solo a set di dati specifici. Se l'applicazione specifica un accesso diverso da quello all'intero account, deve richiedere l'autorizzazione e ottenere un token di accesso per ogni set di dati a cui necessita di accedere. Il parametro x_permissions della richiesta HTTP può specificare una richiesta di accesso all'intero account o a set di dati specifici.

  • Accesso all'intero account

    Per richiedere l'accesso a tutti i set di dati a cui l'utente ha effettuato la sottoscrizione, è necessario assegnare il valore account al parametro x_permissions durante il reindirizzamento al flusso di consenso.
    Esempio: x_permissions=account

  • Accesso a un set di dati specifico

    Per richiedere l'accesso a un set di dati specifico, è necessario assegnare il percorso relativo del set di dati al parametro x_permissions. Il percorso relativo è la parte dell'URL radice del servizio che identifica l'editore e il nome del set di dati. Se ad esempio l'URL radice del servizio è https://datamarket.azure.com/data.ashx/contoso/sales, il percorso relativo sarà contoso/sales.
    Esempio: x_required_offers=contoso/sales

    Per individuare l'URL radice del servizio

    1. Visitare Marketplace nel browser ed effettuare l'accesso.

    2. Fare clic su Dati personali.

    3. Individuare il set di dati desiderato. Se non è presente nell'elenco, è necessario effettuare la sottoscrizione. Per informazioni, vedere Effettuare la sottoscrizione a un'offerta di dati.

    4. Fare clic su Utilizza nella parte destra della schermata.

    5. Scorrere la pagina verso il basso e fare clic sulla scheda Dettagli.

    6. Individuare l'URL radice del servizio nella parte superiore della pagina. Annotarlo per un successivo utilizzo.

  • Accesso a un set di dati richiesto

    Anziché limitare le autorizzazioni a un set di dati specifico, un'applicazione può richiedere che un utente disponga di un set di dati specifico. In questo modo il flusso di consenso verrà completato solo se l'utente dispone di una sottoscrizione attiva a un set di dati. Per utilizzare questa opzione, specificare un identificatore di offerta nel parametro x_required_offers anziché nel parametro x_permissions.

Il tipo di una richiesta sul lato client è sempre code (request_type=code).

Se l'applicazione richiede l'accesso a tutti i set di dati a cui l'utente ha effettuato la sottoscrizione (x_permissions=account), viene visualizzata la schermata di concessione esplicita nella quale l'utente può fare clic su Consenti accesso o Annulla.

Se l'applicazione richiede uno o più set di dati specifici, l'utente potrebbe disporre o meno di una sottoscrizione a tutti. Se l'utente dispone di una sottoscrizione a ogni set di dati richiesto, viene visualizzata la schermata di concessione esplicita (vedere sopra) nella quale l'utente può fare clic su Consenti accesso o Annulla. Se l'utente non dispone della sottoscrizione a uno o più set di dati richiesti, può scegliere se effettuare la sottoscrizione o annullare l'operazione.

L'applicazione indica un set di dati specifico nella richiesta assegnando al parametro x_permissions uno specifico ID di offerta nel formato DataOwner/Dataset.

Se l'applicazione richiede uno o più set di dati specifici, l'utente potrebbe disporre o meno di una sottoscrizione a tutti. L'applicazione avrà accesso a un set di dati solo se un utente dispone di una sottoscrizione attiva, a meno che l'applicazione non utilizzi il parametro della stringa di query x_required_offers.

Affinché l'applicazione riceva un codice di autenticazione da Marketplace, deve prima essere registrata in Marketplace. Quando si registra l'applicazione in Marketplace, vengono assegnati un ID applicazione e un segreto che saranno utilizzati durante il processo di autenticazione e autorizzazione.

Processo dell'applicazione

  1. Eseguire l'accesso a Marketplace.

  2. Visitare https://datamarket.azure.com/developer/applications nel browser.

  3. Fare clic su Crea.

  4. Immettere un ID univoco per l'applicazione.
    Esempio: MiaApp10

    ImportantImportante
    L'ID può essere impostato solo durante la creazione della registrazione e non può essere cambiato durante un'eventuale successiva modifica della registrazione.

  5. Immettere il nome dell'applicazione.
    Esempio: Mia Applicazione 1.0

  6. Immettere l'URI di reindirizzamento post-consenso dell'applicazione.

    L'URI di reindirizzamento post-consenso dell'applicazione è l'URL a cui viene reindirizzato il browser dell'utente al termine del flusso di consenso.

  7. Fare clic su Salva.

L'endpoint del flusso di consenso OAuth supporta i parametri della stringa di query impostabili nel client riportati di seguito.

 

Parametro Obbligatorio/Facoltativo Descrizione

client_id

Obbligatorio

L'ID client registrato in Marketplace.

redirect_uri

Facoltativo

Se questo parametro viene specificato, il sistema verifica che corrisponda all'URI di reindirizzamento registrato in precedenza per il client. In caso di corrispondenza, tutto eccetto la stringa di query deve avere lo stesso formato canonico.

Se questo parametro non viene specificato, per impostazione predefinita viene utilizzato l'URI registrato in precedenza.

response_type

Obbligatorio

Marketplace supporta solo il parametro code.

x_permissions

Obbligatorio

Se è specificata la parola account, tutti i token di accesso risultanti dalla concessione del consenso hanno accesso a tutte le offerte correnti e future. Se è specificato un identificatore di offerta, l'ambito di tutti i token di accesso risultanti dalla concessione del consenso viene limitato in modo da consentire l'accesso alla sola offerta specificata.

Se è specificato un identificatore di offerta, l'ambito di tutti i token di accesso risultanti dalla concessione del consenso viene limitato in modo da consentire l'accesso alla sola offerta specificata.

state

Facoltativo

Un valore opaco passato tra la richiesta e la richiamata.

x_required_offers

Facoltativo

Un ID di offerta che utilizza lo stesso formato del parametro x_permissions.

Per SU2 l'elenco è limitato a una sola offerta.

Se questo parametro viene specificato, il sistema verifica che l'account disponga di una sottoscrizione attiva a tutte le offerte nell'elenco prima di restituire una risposta positiva.

L'offerta presente in questo elenco viene inclusa in modo implicito nel parametro x_permissions per determinare l'ambito del token di accesso.

È possibile aggiungere a un'offerta un requisito di transazione minimo. In tal caso, il sistema verifica che l'account abbia effettuato la sottoscrizione a una variante di offerta con un limite mensile pari o superiore al numero specificato in questo parametro.

Di seguito è riportata la matrice dei parametri x_permissions e x_required_offers. È inoltre indicato se sono supportati e il comportamento risultante di Marketplace.

 

x_permissions x_required_offers Comportamento risultante

Null

Null

Errore

account

Null

Concessione esplicita per l'intero account.

account

Un ID di offerta

Concessione esplicita per l'intero account e acquisto incorporato per l'offerta.

account

Più ID di offerta

Errore

Uno o più ID di offerta

Null

Errore

Stesso ID di offerta di x_required_offers

Un ID di offerta

Acquisto incorporato per l'offerta.
Accesso solo all'offerta acquistata.

Stesso ID di offerta di x_required_offers

Più ID di offerta

Errore

Null

Un ID di offerta

Acquisto incorporato per l'offerta.
Accesso solo all'offerta acquistata.

Di seguito sono riportati le condizioni di errore e i messaggi che possono essere visualizzati all'utente durante il reindirizzamento al flusso di consenso.

 

Condizione di errore Messaggio

Il valore della stringa di query per response_type non è presente o non è supportato.

<h1>Richiesta non valida</h1>
<p>L'applicazione in uso ha inviato una richiesta non valida a Marketplace. Contattare il fornitore dell'applicazione per segnalare l'errore.</p>
<p>Parametro <param/> assente o contenente un valore non supportato.</p>

Il valore della stringa di query per x_required_offers contiene identificatori di offerta inesistenti.

<h1>Richiesta non valida</h1>
<p>L'applicazione in uso ha inviato una richiesta non valida a Marketplace. Contattare il fornitore dell'applicazione per segnalare l'errore.</p>
<p>Offerta inesistente: <IDOffertaNonValido></p>

Il valore della stringa di query per client_id non è valido, il che significa che il parametro client_id non è registrato in Marketplace.

<h1>Richiesta non valida</h1>
<p>L'applicazione in uso ha inviato una richiesta non valida a Marketplace. Contattare il fornitore dell'applicazione per segnalare l'errore.</p>
<p>Applicazione non registrata: <IDClient></p>

Il valore della stringa di query per client_id è mappato a un'applicazione sospesa.

<h1>Richiesta non valida</h1>
<p>L'applicazione in uso ha inviato una richiesta non valida a Marketplace. Contattare il fornitore dell'applicazione per segnalare l'errore.</p>
<p>Applicazione sospesa: <IDClient></p>

Troppe voci x_permissions o x_required_offers.

<h1>Richiesta non valida</h1>
<p>L'applicazione in uso ha inviato una richiesta non valida a Marketplace. Contattare il fornitore dell'applicazione per segnalare l'errore.</p>
<p>Presenti oltre 50 identificatori per x_permissions o x_required_offers.</p>

Vedere anche

Il documento è risultato utile?
(1500 caratteri rimanenti)
Grazie per i commenti inviati.
Mostra:
© 2014 Microsoft