Azure AD B2C: richiesta di token di accessoAzure AD B2C: Requesting access tokens

Un token di accesso, indicato come access_token nelle risposte da Azure AD B2C, è un tipo di token di sicurezza che un client può usare per accedere alle risorse protette da un server di autorizzazione, ad esempio un'API Web.An access token (denoted as access_token in the responses from Azure AD B2C) is a form of security token that a client can use to access resources that are secured by an authorization server, such as a web API. I token di accesso sono rappresentati come token JWT e contengono informazioni sui server della risorsa desiderata e le autorizzazioni concesse al server.Access tokens are represented as JWTs and contain information about the intended resource server and the granted permissions to the server. Quando si chiama il server delle risorse, il token di accesso deve essere presente nella richiesta HTTP.When calling the resource server, the access token must be present in the HTTP request.

Questo articolo descrive come configurare un'applicazione client e un'API Web per ottenere un oggetto access_token.This article discusses how to configure a client application and web API in order to obtain an access_token.

Nota

Le catene di API Web (On-Behalf-Of) non sono supportate da Azure Active Directory B2C.Web API chains (On-Behalf-Of) is not supported by Azure AD B2C.

Molte architetture includono un'API Web che deve chiamare un'altra API Web downstream, entrambe protette da Azure AD B2C.Many architectures include a web API that needs to call another downstream web API, both secured by Azure AD B2C. Questo scenario è comune nei client nativi che hanno un back-end dell'API Web, che a sua volta chiama un servizio online Microsoft come l'API Graph di Azure AD.This scenario is common in native clients that have a web API back end, which in turn calls a Microsoft online service such as the Azure AD Graph API.

Questo scenario di API Web concatenate può essere supportato tramite la concessione di credenziali del bearer token JWT di OAuth 2.0, nota anche come flusso On-Behalf-Of.This chained web API scenario can be supported by using the OAuth 2.0 JWT Bearer Credential grant, otherwise known as the On-Behalf-Of flow. Il flusso On-Behalf-Of, tuttavia, non è attualmente implementato in Azure AD B2C.However, the On-Behalf-Of flow is not currently implemented in Azure AD B2C.

Registrare un'API Web e pubblicare le autorizzazioniRegister a web API and publish permissions

Prima di richiedere un token di accesso, è necessario registrare un'API Web e pubblicare le autorizzazioni (ambiti) che possono essere concesse all'applicazione client.Before requesting an access token, you first need to register a web API and publish permissions (scopes) that can be granted to the client application.

Registrare un'API WebRegister a web API

  1. Nel menu delle funzionalità di Azure AD B2C nel portale di Azure fare clic su Applicazioni.On the Azure AD B2C features menu on the Azure portal, click Applications.
  2. Fare clic su +Aggiungi nella parte superiore del menu.Click +Add at the top of the menu.
  3. Immettere un nome per l'applicazione che descriva l'applicazione agli utenti.Enter a Name for the application that will describe your application to consumers. Ad esempio, è possibile immettere "API Contoso".For example, you could enter "Contoso API".
  4. Attivare/Disattivare l'opzione Includi app Web/API Web impostandola su .Toggle the Include web app / web API switch to Yes.
  5. Immettere un valore arbitrario per URL di risposta.Enter an arbitrary value for the Reply URLs. Ad esempio, immettere https://localhost:44316/.For example, enter https://localhost:44316/. Il valore non è importante, perché un'API non dovrà ricevere il token direttamente da Azure AD B2C.The value does not matter since an API should not be receiving the token directly from Azure AD B2C.
  6. Immettere un URI ID app.Enter an App ID URI. Questo è l'identificatore usato per l'API Web.This is the identifier used for your web API. Ad esempio, immettere "notes" nella casella.For example, enter 'notes' in the box. Per URI ID app il valore sarà quindi https://{tenantName}.onmicrosoft.com/notes.The App ID URI would then be https://{tenantName}.onmicrosoft.com/notes.
  7. Fare clic su Crea per registrare l'applicazione.Click Create to register your application.
  8. Fare clic sull'applicazione appena creata e copiare l' ID client applicazione univoco globale che verrà usato in seguito nel codice.Click the application that you just created and copy down the globally unique Application Client ID that you'll use later in your code.

Pubblicazione delle autorizzazioniPublishing permissions

Gli ambiti, analoghi alle autorizzazioni, sono necessari quando l'app chiama un'API.Scopes, which are analogous to permissions, are necessary when your app is calling an API. Alcuni esempi di ambiti sono "read" e "write".Some examples of scopes are "read" or "write". Si supponga di voler fare in modo che l'app Web o nativa possa leggere da un'API.Suppose you want your web or native app to "read" from an API. L'app chiama Azure AD B2C e richiede un token di accesso che dia accesso all'ambito "read".Your app would call Azure AD B2C and request an access token that gives access to the scope "read". Perché Azure AD B2C emetta questo token di accesso, l'API specifica deve concedere l'autorizzazione di lettura all'app.In order for Azure AD B2C to emit such an access token, the app needs to be granted permission to "read" from the specific API. A questo scopo, l'API deve prima di tutto pubblicare l'ambito "read".To do this, your API first needs to publish the "read" scope.

  1. Nel menu Applicazioni di Azure AD B2C aprire l'applicazione API Web ("API Contoso").Within the Azure AD B2C Applications menu, open the web API application ("Contoso API").
  2. Fare clic su Ambiti pubblicati.Click on Published scopes. È possibile definire qui le autorizzazioni (ambiti) che possono essere concesse ad altre applicazioni.This is where you define the permissions (scopes) that can be granted to other applications.
  3. Configurare i campi Valore ambito nel modo necessario, ad esempio "read".Add Scope Values as necessary (for example, "read"). Per impostazione predefinita, verrà definito l'ambito "user_impersonation",By default, the "user_impersonation" scope will be defined. che può essere ignorato se lo si desidera.You can ignore this if you wish. Immettere una descrizione dell'ambito nella colonna Nome ambito.Enter a description of the scope in the Scope Name column.
  4. Fare clic su Save.Click Save.

Importante

Nome ambito è la descrizione di Valore ambito.The Scope Name is the description of the Scope Value. Quando si usa l'ambito, assicurarsi di usare Valore ambito.When using the scope, make sure to use the Scope Value.

Concedere a un'app Web o nativa le autorizzazioni per un'API WebGrant a native or web app permissions to a web API

Dopo aver configurato un'API per la pubblicazione degli ambiti, è necessario concedere gli ambiti all'applicazione client tramite il portale di Azure.Once an API is configured to publish scopes, the client application needs to be granted those scopes via the Azure portal.

  1. Passare al menu Applicazioni nel menu delle funzionalità di Azure AD B2C.Navigate to the Applications menu in the Azure AD B2C features menu.
  2. Registrare un'applicazione client (applicazione web o client nativo) se non è già disponibile.Register a client application (web app or native client) if you don’t have one already. Se si segue questa guida come punto di partenza, sarà necessario registrare un'applicazione client.If you are following this guide as your starting point, you'll need to register a client application.
  3. Fare clic su Accesso all'API.Click on API access.
  4. Fare clic su Aggiungi.Click on Add.
  5. Selezionare l'API Web e gli ambiti (autorizzazioni) che si desidera concedere.Select your web API and the scopes (permissions) you would like to grant.
  6. Fare clic su OK.Click OK.

Nota

Azure AD B2C non richiede il consenso agli utenti dell'applicazione client.Azure AD B2C does not ask your client application users for their consent. Al contrario, tutti i consensi vengono concessi dall'amministratore, in base alle autorizzazioni configurate tra le applicazioni descritte in precedenza.Instead, all consent is provided by the admin, based on the permissions configured between the applications described above. Se è stata revocata un'autorizzazione concessa per un'applicazione, tutti gli utenti che in precedenza potevano acquisire tale autorizzazione non saranno più in grado di farlo.If a permission grant for an application is revoked, all users who were previously able to acquire that permission will no longer be able to do so.

Richiesta di un tokenRequesting a token

Quando si richiede un token di accesso, l'applicazione client deve specificare le autorizzazioni desiderate nel parametro scope della richiesta.When requesting an access token, the client application needs to specify the desired permissions in the scope parameter of the request. Ad esempio, per specificare "read" per Valore ambito per l'API con URI ID app impostato su https://contoso.onmicrosoft.com/notes, l'ambito sarà https://contoso.onmicrosoft.com/notes/read.For example, to specify the Scope Value “read” for the API that has the App ID URI of https://contoso.onmicrosoft.com/notes, the scope would be https://contoso.onmicrosoft.com/notes/read. Di seguito è riportato un esempio di una richiesta di codice di autorizzazione per l'endpoint /authorize.Below is an example of an authorization code request to the /authorize endpoint.

Nota

Attualmente i domini personalizzati non sono supportati insieme ai token di accesso.Currently, custom domains are not supported along with access tokens. È necessario usare il dominio NomeTenant.onmicrosoft.com nell'URL della richiesta.You must use your tenantName.onmicrosoft.com domain in the request URL.

https://login.microsoftonline.com/<tenantName>.onmicrosoft.com/oauth2/v2.0/authorize?p=<yourPolicyId>&client_id=<appID_of_your_client_application>&nonce=anyRandomValue&redirect_uri=<redirect_uri_of_your_client_application>&scope=https%3A%2F%2Fcontoso.onmicrosoft.com%2Fnotes%2Fread&response_type=code 

Per acquisire più autorizzazioni nella stessa richiesta, è possibile aggiungere più voci nell'unico parametro scope, separato da spazi.To acquire multiple permissions in the same request, you can add multiple entries in the single scope parameter, separated by spaces. Ad esempio: For example:

URL decodificato:URL decoded:

scope=https://contoso.onmicrosoft.com/notes/read openid offline_access

URL codificato:URL encoded:

scope=https%3A%2F%2Fcontoso.onmicrosoft.com%2Fnotes%2Fread%20openid%20offline_access

È possibile richiedere più ambiti (autorizzazioni) per una risorsa rispetto a quelli concessi per l'applicazione client.You may request more scopes (permissions) for a resource than what is granted for your client application. In questo caso, la chiamata avrà esito positivo se almeno un'autorizzazione viene concessa.When this is the case, the call will succeed if at least one permission is granted. L'attestazione "scp" dell'access_token risultante sarà popolata con solo le autorizzazioni concesse.The resulting access_token will have its “scp” claim populated with only the permissions that were successfully granted.

Nota

La richiesta di autorizzazioni per due risorse Web diverse nella stessa richiesta non è supportata.We do not support requesting permissions against two different web resources in the same request. Questo tipo di richiesta avrà esito negativo.This kind of request will fail.

Casi specialiSpecial cases

Lo standard OpenID Connect consente di specificare valori speciali diversi per "scope".The OpenID Connect standard specifies several special “scope” values. Gli ambiti speciali seguenti rappresentano l'autorizzazione per "accedere al profilo dell'utente":The following special scopes represent the permission to “access the user’s profile”:

Se il parametro response_type in una richiesta /authorize include token, il parametro scope deve includere almeno un ambito delle risorse (diverso da openid e offline_access) che verrà concesso.If the response_type parameter in a /authorize request includes token, the scope parameter must include at least one resource scope (other than openid and offline_access) that will be granted. In caso contrario, la richiesta /authorize verrà terminata con un errore.Otherwise, the /authorize request will terminate with a failure.

Token restituitoThe returned token

In un access_token creato correttamente (da un endpoint /authorize o /token), saranno presenti le attestazioni seguenti:In a successfully minted access_token (from either the /authorize or /token endpoint), the following claims will be present:

NOMEName AttestazioneClaim DESCRIZIONEDescription
AudienceAudience aud L'ID applicazione della singola risorsa per cui il token concede l'accesso.The application ID of the single resource that the token grants access to.
ScopeScope scp Le autorizzazioni concesse alla risorsa.The permissions granted to the resource. Le autorizzazioni multiple concesse saranno separate da spazi.Multiple granted permissions will be separated by space.
Entità autorizzatiAuthorized Party azp L'ID applicazione dell'applicazione client che ha avviato la richiesta.The application ID of the client application that initiated the request.

Quando l'API riceve access_token, deve convalidare il token per dimostrarne l'autenticità e la presenza dell'attestazione corretta.When your API receives the access_token, it must validate the token to prove that the token is authentic and has the correct claims.

Commenti e suggerimenti sono sempre graditi.We are always open to feedback and suggestions! In caso di difficoltà con questo argomento, inserire un post in Stack Overflow usando il tag 'azure-ad-b2c'.If you have any difficulties with this topic, please post on Stack Overflow using the tag 'azure-ad-b2c'. Le richieste di funzionalità possono essere aggiunte in UserVoice.For feature requests, add them to UserVoice.

Passaggi successiviNext steps