Usare token di accesso limitati per Viso

I fornitori di software indipendenti (ISV) possono gestire l'uso dell'API Viso dei client emettendo token di accesso che concedono l'accesso alle funzionalità viso normalmente gestite. Ciò consente alle aziende client di usare l'API Viso senza dover eseguire il processo di approvazione formale.

Questa guida illustra come generare i token di accesso, se si è un ISV approvato e come usare i token se si è un client.

La funzionalità di token di accesso limitato fa parte del servizio token degli strumenti Foundry esistente. È stata aggiunta una nuova operazione allo scopo di ignorare il controllo di accesso limitato per gli scenari approvati.

Importante

Solo agli ISV che superano i requisiti di controllo verrà concesso l'accesso a questa funzionalità. Per richiedere l'approvazione, contattare azureface@microsoft.com.

Prerequisiti

cURL installato (o un altro strumento in grado di effettuare richieste HTTP).
L'ISV deve avere una risorsa Viso di Azure o una risorsa Foundry Tools multi-servizio.
Il client deve avere una risorsa Viso di Azure.

Esempio di caso d'uso

Un'azienda di esempio vende software che usa il servizio Viso di Azure per gestire i sistemi di sicurezza degli accessi alle porte. I loro clienti, i singoli produttori di dispositivi porta, sottoscrivono il software e lo eseguono nei loro dispositivi. Queste aziende client vogliono effettuare chiamate API Viso dai propri dispositivi per eseguire operazioni di accesso limitato, ad esempio l'identificazione del viso. Basandosi sui token di accesso dell'ISV, è possibile ignorare il processo di approvazione formale per l'identificazione del viso. L'ISV, che è già stato approvato, può concedere i token di accesso JIT client.

Aspettativa di responsabilità

L'ISV che emette il token è responsabile di garantire che i token vengano usati solo per lo scopo approvato.

Se l'ISV apprende che un client usa LimitedAccessToken per scopi non approvati, l'ISV deve interrompere la generazione di token per tale cliente. Microsoft può tenere traccia del rilascio e dell'utilizzo di LimitedAccessTokens e microsoft si riserva il diritto di revocare l'accesso di un ISV all'API issueLimitedAccessToken se l'abuso non viene risolto.

Passaggio 1: l’ISV ottiene l'ID risorsa Viso del client

L'ISV deve configurare un canale di comunicazione tra il proprio servizio cloud sicuro (che genererà il token di accesso) e l'applicazione in esecuzione nel dispositivo del client. L'ID risorsa Viso del client deve essere noto prima di generare LimitedAccessToken.

L'ID risorsa Viso ha il seguente formato:

/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.CognitiveServices/accounts/<face-resource-name>

Per esempio:

/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/client-rg/providers/Microsoft.CognitiveServices/accounts/client-face-api

Passaggio 2: ISV genera un token

Il servizio cloud ISV, in esecuzione in un ambiente sicuro, chiama l'API issueLimitedAccessToken usando l'ID risorsa Viso noto del cliente finale.

Per chiamare l'API issueLimitedAccessToken, copiare il comando cURL seguente in un editor di testo.

curl -X POST 'https://<isv-endpoint>/sts/v1.0/issueLimitedAccessToken?expiredTime=3600' \  
-H 'Ocp-Apim-Subscription-Key: <isv-face-key>' \  
-H 'Content-Type: application/json' \  
-d '{  
    "targetAzureResourceId": "/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.CognitiveServices/accounts/<face-resource-name>",  
    "featureFlags": ["Face.Identification", "Face.Verification"]  
}'

Apportare quindi le modifiche seguenti:

Sostituire <isv-endpoint> con l'endpoint della risorsa ISV. Ad esempio, westus.api.cognitive.microsoft.com.
Facoltativamente, impostare il parametro expiredTime per impostare l'ora di scadenza del token in secondi. Deve essere un valore compreso tra 60 e 86400. Il valore predefinito è 3600 (1 ora).
Sostituire <isv-face-key> con la chiave della risorsa Viso dell’ISV.
Sostituire <subscription-id> con l'ID sottoscrizione della sottoscrizione di Azure del client.
Sostituire <resource-group-name> con il nome del gruppo di risorse del client.
Sostituire <face-resource-name> con il nome della risorsa Viso del client.
Impostare "featureFlags" sul set di ruoli di accesso che si desidera concedere. I flag disponibili sono "Face.Identification", "Face.Verification" e "LimitedAccess.HighRisk". Un ISV può concedere solo le autorizzazioni concesse da Microsoft. Ad esempio, se all'ISV è stato concesso l'accesso all'identificazione del viso, può creare un oggetto LimitedAccessToken per Face.Identification per il client. Tutte le creazioni e gli usi dei token vengono registrati per scopi di utilizzo e sicurezza.

Incollare quindi il comando in una finestra del terminale ed eseguirlo.

L'API deve restituire una risposta 200 con il token sotto forma di token Web JSON (application/jwt). Se si vuole esaminare LimitedAccessToken, è possibile farlo usando JWT.

Passaggio 3: L'applicazione client usa il token

L'applicazione dell’ISV può quindi passare LimitedAccessToken come intestazione della richiesta HTTP per le future richieste API Viso per conto del client. Questo funziona indipendentemente da altri meccanismi di autenticazione, quindi nessuna informazione personale del client viene mai persa all'ISV.

Attenzione

Il client non deve essere a conoscenza del valore del token, perché può essere passato in background. Se il client usasse uno strumento di monitoraggio Web per intercettare il traffico, sarebbe possibile visualizzare l'intestazione LimitedAccessToken. Tuttavia, poiché il token scade dopo un breve periodo di tempo, sono limitati in ciò che possono fare con esso. Questo rischio è noto e considerato accettabile.

È per ogni ISV decidere come passa esattamente il token dal servizio cloud all'applicazione client.

API REST
C#

Una richiesta api Viso di esempio che usa il token di accesso è simile alla seguente:

curl -X POST 'https://<client-endpoint>/face/v1.0/identify' \  
-H 'Ocp-Apim-Subscription-Key: <client-face-key>' \  
-H 'LimitedAccessToken: Bearer <token>' \  
-H 'Content-Type: application/json' \  
-d '{  
  "largePersonGroupId": "sample_group",  
  "faceIds": [  
    "c5c24a82-6845-4031-9d5d-978df9175426",  
    "65d083d4-9447-47d1-af30-b626144bf0fb"  
  ],  
  "maxNumOfCandidatesReturned": 1,  
  "confidenceThreshold": 0.5  
}'

Annotazioni

L'URL dell'endpoint e la chiave viso appartengono alla risorsa Viso del client, non alla risorsa ISV. <token> viene passato come intestazione di richiesta HTTP.

I frammenti di codice seguenti illustrano come usare un token di accesso con Face SDK per C#.

La classe seguente usa un token di accesso per creare un oggetto HttpPipelineSynchronousPolicy che può essere usato per autenticare un oggetto client dell'API Viso. Aggiunge automaticamente il token di accesso come intestazione in ogni richiesta che verrà eseguita dal client Viso.

public class LimitedAccessTokenPolicy : HttpPipelineSynchronousPolicy
{
    /// <summary>
    /// Creates a new instance of the LimitedAccessTokenPolicy class
    /// </summary>
    /// <param name="limitedAccessToken">LimitedAccessToken to bypass the limited access program, requires ISV sponsership.</param>
    public LimitedAccessTokenPolicy(string limitedAccessToken)
    {
        _limitedAccessToken = limitedAccessToken;
    }

    private readonly string _limitedAccessToken;

    /// <summary>
    /// Add the authentication header to each outgoing request
    /// </summary>
    /// <param name="message">The outgoing message</param>
    public override void OnSendingRequest(HttpMessage message)
    {
        message.Request.Headers.Add("LimitedAccessToken", $"Bearer {_limitedAccessToken}");
    }
}

Nell'applicazione lato client la classe helper può essere usata come nell'esempio seguente:

static void Main(string[] args)
{
    // create Face client object
    var clientOptions = new AzureAIVisionFaceClientOptions();
    clientOptions.AddPolicy(new LimitedAccessTokenPolicy("<token>"), HttpPipelinePosition.PerCall);
    FaceClient faceClient = new FaceClient(new Uri("<client-endpoint>"), new AzureKeyCredential("<client-face-key>"), clientOptions);

    // use Face client in an API call
    using (var stream = File.OpenRead("photo.jpg"))
    {
        var response = faceClient.Detect(BinaryData.FromStream(stream), FaceDetectionModel.Detection03, FaceRecognitionModel.Recognition04, returnFaceId: true);

        Console.WriteLine(JsonConvert.SerializeObject(response.Value));
    }
}

Commenti e suggerimenti

Questa pagina è stata utile?

Last updated on 2026-03-19