Utilizzare il flusso di concessione implicita OAuth 2.0 nel portale
Nota
A partire dal 12 ottobre 2022, i portali Power Apps sono denominati Power Pages. Altre informazioni: Microsoft Power Pages è ora generalmente disponibile (blog)
A breve verrà eseguita la migrazione e l'unione della documentazione dei portali Power Apps con la documentazione di Power Pages.
Questa funzionalità consente a un cliente di eseguire chiamate sul lato client ad API esterne e di proteggerle utilizzando il flusso di concessione implicita OAuth 2.0. Fornisce un endpoint per ottenere token di accesso sicuri. Questi token conterranno informazioni sull'identità dell'utente utilizzabili da API esterne per l'autorizzazione in base al flusso di concessione implicita OAuth 2.0. Le informazioni sull'identità di un utente che ha effettuato l'accesso vengono trasmesse in modo protetto alle chiamate AJAX esterne, il che aiuta gli sviluppatori a passare il contesto di autenticazione e anche gli utenti a proteggere le proprie API.
Il flusso di concessione implicita OAuth 2.0 supporta endpoint token che un client può chiamare per ottenere un token ID.
Certificati personalizzati
L'uso del certificato predefinito per il flusso concessione implicita OAuth 2.0 è deprecato. Sarà necessario utilizzare un certificato personalizzato durante l'utilizzo dell'endpoint OAuth 2.0. Utilizza l'interfaccia di amministrazione di Power Platform per caricare il certificato personalizzato. Dopo aver caricato il certificato personalizzato, è necessario aggiornare le impostazioni del sito come indicato di seguito:
Passa alle impostazioni del portale e seleziona Impostazioni sito.
Per creare una nuova impostazione, seleziona Nuova.
Per modificare un'impostazione esistente, seleziona l'impostazione sito elencata nella griglia.
Specifica i valori:
- Nome: CustomCertificates/ImplicitGrantflow
- Sito Web: il sito Web associato
- Valore: copia l'identificazione personale del certificato personalizzato caricato dalla schermata Gestisci certificato personalizzato e incollala qui. Il valore indicherà quale certificato verrà utilizzato per il flusso di concessione implicita.
Seleziona Salva e chiudi.
Dettagli dell'endpoint token
Puoi anche ottenere un token eseguendo una richiesta di pubblicazione all'endpoint /token. L'URL per l'endpoint token è: <portal_url>/_services/auth/token. L'endpoint token supporta i parametri seguenti:
| Parametro | Necessario? | Descrizione |
|---|---|---|
| client_id | No | Stringa che viene passata si effettua una chiamata all'endpoint authorize. Devi assicurarti che l'ID client è registrato con il portale. In caso contrario, viene visualizzato un errore. L'ID client viene aggiunto nelle attestazioni nel token come parametro aud e appid e può essere utilizzato dal client per convalidare che il token restituito è per la relativa app.La lunghezza massima è 36 caratteri. Solo i caratteri alfanumerici e i trattini sono supportati. |
| redirect_uri | No | URL del portale dove le risposte di autenticazione possono essere inviate e ricevute. Deve essere registrato per il particolare client_id utilizzato nella chiamata e deve essere uguale al valore registrato. |
| state | No | Valore incluso nella richiesta che viene restituito anche nella risposta del token. Può essere una stringa di qualsiasi contenuto che intendi utilizzare. In genere, un valore univoco generato a caso viene utilizzato per impedire tentativi di attacco CSRF. La lunghezza massima è 20 caratteri. |
| nonce | No | Valore stringa inviato dal client incluso nel token ID risultante come attestazione. Il client può quindi verificare questo valore per mitigare gli attacchi di tipo replay al token. La lunghezza massima è 20 caratteri. |
| response_type | No | Questo parametro supporta solo token come valore, consentendo all'app di ricevere immediatamente un token di accesso dell'endpoint authorize senza effettuare una seconda richiesta a tale endpoint. |
Nota
Anche se i parametri client_id, redirect_uri, state e nonce sono facoltativi, è consigliabile utilizzarli per avere la certezza che le integrazioni siano protette.
Risposta riuscita
L'endpoint token restituisce state e expires_in come intestazioni di risposta e token nel corpo del modulo.
Risposta con errore
L'errore in un endpoint token viene restituito come documento JSON con i valori seguenti:
- ID errore: identificatore univoco dell'errore.
- Messaggio di errore: messaggio di errore specifico utile per identificare la causa principale di un errore di autenticazione.
- ID correlazione: un GUID utilizzato per il debug. Se hai abilitato la registrazione diagnostica, l'ID correlazione è presente nei registri di errore del server.
- Timestamp: data e ora in cui l'errore è stato generato.
Il messaggio di errore viene visualizzato nella lingua predefinita dell'utente connesso. Se l'utente non è connesso, viene visualizzata la pagina per eseguire l'accesso. Ad esempio, una risposta con errore appare come segue:
{"ErrorId": "PortalSTS0001", "ErrorMessage": "Client Id provided in the request is not a valid client Id registered for this portal. Please check the parameter and try again.", "Timestamp": "4/5/2019 10:02:11 AM", "CorrelationId": "7464eb01-71ab-44bc-93a1-f221479be847" }
Dettagli dell'endpoint di autorizzazione
Nota
L'endpoint di autorizzazione è deprecato. Usa la richiesta POST dell'endpoint token per ottenere il token ID.]
L'URL per l'endpoint di autorizzazione è: <portal_url>/_services/auth/authorize. L'endpoint di autorizzazione supporta i parametri seguenti:
| Parametro | Necessario? | Descrizione |
|---|---|---|
| client_id | Sì | Stringa che viene passata si effettua una chiamata all'endpoint authorize. Devi assicurarti che l'ID client è registrato con il portale. In caso contrario, viene visualizzato un errore. L'ID client viene aggiunto nelle attestazioni nel token come parametro aud e appid e può essere utilizzato dal client per convalidare che il token restituito è per la relativa app.La lunghezza massima è 36 caratteri. Solo i caratteri alfanumerici e i trattini sono supportati. |
| redirect_uri | Sì | URL del portale dove le risposte di autenticazione possono essere inviate e ricevute. Deve essere registrato per il particolare client_id utilizzato nella chiamata e deve essere uguale al valore registrato. |
| state | No | Valore incluso nella richiesta che viene restituito anche nella risposta del token. Può essere una stringa di qualsiasi contenuto che intendi utilizzare. In genere, un valore univoco generato a caso viene utilizzato per impedire tentativi di attacco CSRF. La lunghezza massima è 20 caratteri. |
| nonce | No | Valore stringa inviato dal client incluso nel token ID risultante come attestazione. Il client può quindi verificare questo valore per mitigare gli attacchi di tipo replay al token. La lunghezza massima è 20 caratteri. |
| response_type | No | Questo parametro supporta solo token come valore, consentendo all'app di ricevere immediatamente un token di accesso dell'endpoint authorize senza effettuare una seconda richiesta a tale endpoint. |
Risposta riuscita
L'endpoint authorize restituisce i seguenti valori nell'URL di risposta come frammento:
- token: Il token viene restituito come Token Web JSON (JWT) firmato dalla chiave privata del portale.
- stato: se un parametro state è incluso nella richiesta, lo stesso valore deve essere visualizzato nella risposta. L'app deve verificare che i valori state nella richiesta e nella risposta siano identici.
- expires_in: la validità del token di accesso (in secondi).
Ad esempio, una risposta riuscita appare come segue:
GET https://aadb2cplayground.azurewebsites.net/#token=eyJ0eXAiOiJKV1QiLCJhbGciOI1NisIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q&expires_in=3599&state=arbitrary_data_you_sent_earlier
Risposta con errore
L'errore nell'endpoint authorize viene restituito come documento JSON con i valori seguenti:
- ID errore: identificatore univoco dell'errore.
- Messaggio di errore: messaggio di errore specifico utile per identificare la causa principale di un errore di autenticazione.
- ID correlazione: un GUID utilizzato per il debug. Se hai abilitato la registrazione diagnostica, l'ID correlazione è presente nei registri di errore del server.
- Timestamp: data e ora in cui l'errore è stato generato.
Il messaggio di errore viene visualizzato nella lingua predefinita dell'utente connesso. Se l'utente non è connesso, viene visualizzata la pagina per eseguire l'accesso. Ad esempio, una risposta con errore appare come segue:
{"ErrorId": "PortalSTS0001", "ErrorMessage": "Client Id provided in the request is not a valid client Id registered for this portal. Please check the parameter and try again.", "Timestamp": "4/5/2019 10:02:11 AM", "CorrelationId": "7464eb01-71ab-44bc-93a1-f221479be847" }
Convalidare il token ID
Ottenere un token ID non è sufficiente per l'autenticazione dell'utente; devi anche convalidare la firma del token e verificare le attestazioni nel token in base ai requisiti dell'app. L'endpoint token pubblico fornisce la chiave pubblica del portale, che può essere utilizzata per convalidare la firma del token fornito dal portale. L'URL per l'endpoint token pubblico è: <portal_url>/_services/auth/publickey.
Attivare o disattivare il flusso di concessione implicita
Per impostazione predefinita, il flusso di concessione implicita è abilitato. Se vuoi disattivarlo, imposta il valore dell'impostazione di sito Connector/ImplicitGrantFlowEnabled su False.
Se questa impostazione di sito non è disponibile nel portale, devi creare una nuova impostazione di sito con il valore appropriato.
Configurare la validità del token
Per impostazione predefinita, il token è valido per 15 minuti. Se desideri modificare la validità del token, imposta il valore dell'impostazione di sito ImplicitGrantFlow/TokenExpirationTime sul valore necessario. Il valore deve essere specificato in secondi. Il valore massimo può essere 1 ora e il valore minimo deve essere 1 minuto. Se specifichi un valore non corretto (ad esempio caratteri alfanumerici), viene utilizzato il valore predefinito di 15 minuti. Se specifichi un valore superiore al valore massimo o inferiore al valore minimo, per impostazione predefinita vengono usati rispettivamente il valore massimo e il valore minimo.
Ad esempio, per impostare la validità del token su 30 minuti, imposta il valore dell'impostazione di sito ImplicitGrantFlow/TokenExpirationTime su 1800. Per impostare la validità del token su 1 ora, imposta il valore dell'impostazione di sito ImplicitGrantFlow/TokenExpirationTime su 3600.
Registrare l'ID client per il flusso di concessione implicita
Devi registrare l'ID client con il portale per il quale tale flusso è consentito. Per registrare un ID client, devi creare le seguenti impostazioni di sito:
| Impostazione di sito | Value |
|---|---|
| ImplicitGrantFlow/RegisteredClientId | I valori di ID cliente validi consentiti per il portale. I valori devono essere separati da un punto e virgola e possono contenere caratteri alfanumerici e trattini. La lunghezza massima è 36 caratteri. |
| ImplicitGrantFlow/{ClientId}/RedirectUri | Gli URL di reindirizzamento validi consentiti per uno specifico ID client. I valori devono essere separati da un punto e virgola. L'URL fornito deve essere una pagina Web valida del portale. |
Codice di esempio
Puoi utilizzare il seguente codice di esempio per iniziare a utilizzare la concessione implicita OAuth 2.0 con le API dei portali Power Apps.
Utilizzare il token OAuth del portale con un'API Web esterna
Questo esempio è un progetto basato su ASP.NET e viene utilizzato per convalidare il token ID pubblicato dai portali Power Apps. L'esempio completo è disponibile in Utilizzare il token OAuth del portale con un'API Web esterna.
Esempio di endpoint token
In questo esempio viene illustrato come utilizzare la funzione getAuthenticationToken per recuperare un token ID utilizzando l'endpoint token nei portali Power Apps. L'esempio è disponibile in Esempio di endpoint token.
Nota
Puoi indicarci le tue preferenze di lingua per la documentazione? Partecipa a un breve sondaggio. (il sondaggio è in inglese)
Il sondaggio richiederà circa sette minuti. Non viene raccolto alcun dato personale (Informativa sulla privacy).