Microsoft Identity Platform e credenziali di tipo password del proprietario della risorsa OAuth 2.0

Articolo
04/08/2024

Microsoft Identity Platform supporta la concessione delle credenziali della password del proprietario della risorsa OAuth 2.0 ( ROPC), che consente a un'applicazione di accedere all'utente gestendo direttamente la password. Questo articolo descrive come programmare direttamente in base al protocollo nell'applicazione. Quando possibile, è consigliabile usare le librerie di autenticazione Microsoft (MSAL) supportate anziché acquisire i token e chiamare le API Web protette. Vedere anche le app di esempio che usano MSAL.

Avviso

Microsoft consiglia di non usare il flusso ROPC. Per la maggior parte degli scenari sono disponibili e consigliate alternative più sicure. Questo flusso richiede un livello di attendibilità molto elevato nell'applicazione e comporta rischi che non sono presenti in altri flussi. È consigliabile usare questo flusso solo quando altri flussi più sicuri non sono validi.

Importante

Microsoft Identity Platform supporta solo la concessione ROPC all'interno dei tenant di Microsoft Entra, non gli account personali. Questo significa che è necessario usare un endpoint specifico del tenant (https://login.microsoftonline.com/{TenantId_or_Name}) o l'endpoint organizations.
Gli account personali invitati a un tenant di Microsoft Entra non possono usare il flusso ROPC.
Gli account che non dispongono di password non possono accedere con ROPC, ovvero funzionalità come l'accesso TRAMITE SMS, FIDO e l'app Authenticator non funzioneranno con tale flusso. Se l'app o gli utenti richiedono queste funzionalità, usare un tipo di concessione diverso da ROPC.
Se gli utenti devono usare Multi-Factor Authentication (MFA) per accedere all'applicazione, saranno invece bloccati.
ROPC non è supportato negli scenari di federazione delle identità ibride, ad esempio Microsoft Entra ID e AD FS usati per autenticare gli account locali. Se gli utenti vengono reindirizzati con l'intera pagina a un provider di identità locale, Microsoft Entra ID non riesce a verificare il nome utente e la password con tale provider di identità. L'autenticazione pass-through è tuttavia supportata con ROPC.
Un'eccezione a uno scenario di federazione di identità ibrida è la seguente: i criteri di individuazione dell'area di autenticazione principale con AllowCloudPasswordValidation impostato su TRUE consentiranno al flusso ROPC di lavorare per gli utenti federati quando una password locale viene sincronizzata nel cloud. Per altre informazioni, vedere Abilitare l'autenticazione ROPC diretta degli utenti federati per le applicazioni legacy.
Le password con spazi vuoti iniziali o finali non sono supportate dal flusso ROPC.

Diagramma del protocollo

Il diagramma seguente mostra il flusso di concessione delle credenziali password del proprietario della risorsa.

Diagram showing the resource owner password credential flow

Richiesta di autorizzazione

Il flusso ROPC è una singola richiesta; invia l'identificazione client e le credenziali dell'utente al provider di identità e riceve i token in cambio. Prima di eseguire questa operazione, il client deve richiedere l'indirizzo di posta elettronica (UPN) e la password dell'utente. Subito dopo una richiesta riuscita, il client deve eliminare in modo sicuro le credenziali dell'utente dalla memoria. Non deve mai salvarle.

// Line breaks and spaces are for legibility only.  This is a public client, so no secret is required.

POST {tenant}/oauth2/v2.0/token
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded

client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&scope=user.read%20openid%20profile%20offline_access
&username=MyUsername@myTenant.com
&password=SuperS3cret
&grant_type=password

Parametro	Condizione	Descrizione
`tenant`	Richiesto	Il tenant della directory in cui si desidera registrare l'utente. Il tenant può essere in formato GUID o nome descrittivo. Tuttavia, il parametro non può essere impostato su `common` o `consumers`, ma può essere impostato su `organizations`.
`client_id`	Richiesto	ID applicazione (client) assegnato all'app dall'interfaccia di amministrazione di Microsoft Entra- Registrazioni app pagina.
`grant_type`	Richiesto	Deve essere impostato su `password`.
`username`	Richiesto	Indirizzo e-mail dell'utente
`password`	Richiesto	Password dell'utente.
`scope`	Consigliato	Un elenco delimitato da spazi di ambiti, o privilegi, richiesti dall'app. In un flusso interattivo l'amministratore o l'utente deve dare il consenso in anticipo a questi ambiti.
`client_secret`	A volte obbligatorio	Se l'app è un client pubblico, l'oggetto `client_secret` o `client_assertion` non può essere incluso. Se l'app è un client riservato, è necessario includerlo.
`client_assertion`	A volte obbligatorio	Una forma diversa di `client_secret`, generata usando un certificato. Per altre informazioni, vedere Credenziali del certificato.

Risposta di autenticazione di esito positivo

Nell'esempio seguente viene illustrata una risposta di token di esito positivo:

{
    "token_type": "Bearer",
    "scope": "User.Read profile openid email",
    "expires_in": 3599,
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...",
    "refresh_token": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4...",
    "id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJub25lIn0.eyJhdWQiOiIyZDRkMTFhMi1mODE0LTQ2YTctOD..."
}

Parametro	Formato	Descrizione
`token_type`	Stringa	Sempre impostato su `Bearer`.
`scope`	Stringhe separate da uno spazio	Se è stato restituito un token di accesso, questo parametro elenca gli ambiti per i quali è valido il token di accesso.
`expires_in`	int	Numero di secondi durante i quali è valido il token di accesso incluso.
`access_token`	Stringa opaca	Emessa per gli ambiti che sono stati richiesti.
`id_token`	Token JSON Web	Emessa nel parametro `scope` originale incluso nell'ambito `openid`.
`refresh_token`	Stringa opaca	Emessa nel parametro `scope` originale incluso `offline_access`.

È possibile usare il token di aggiornamento per acquisire nuovi token di accesso e token di aggiornamento usando lo stesso flusso descritto nella documentazione del flusso del codice OAuth.

Avviso

Non tentare di convalidare o leggere i token per qualsiasi API di cui non si è proprietari, inclusi i token in questo esempio, nel codice. I token per servizi Microsoft possono usare un formato speciale che non verrà convalidato come token JWT e potrebbe anche essere crittografato per gli utenti consumer (account Microsoft). Durante la lettura dei token è uno strumento utile per il debug e l'apprendimento, non assumere dipendenze da questo nel codice o presupporre specifiche sui token che non sono per un'API che si controlla.

Risposta con errore

Se l'utente non ha fornito il nome utente o la password corretti, o il client non ha ricevuto il consenso richiesto, l'autenticazione avrà esito negativo.

Errore	Descrizione	Azione client
`invalid_grant`	L'autenticazione non è riuscita	Le credenziali non sono corrette o il client non ha il consenso per gli ambiti richiesti. Se gli ambiti non sono concessi, verrà restituito un errore `consent_required`. Per risolvere questo errore, il client deve inviare l'utente a un prompt interattivo usando una visualizzazione Web o un browser.
`invalid_request`	La richiesta è stata costruita in modo non corretto	Il tipo di concessione non è supportato nei contesti di autenticazione `/common` o `/consumers`. Usare invece `/organizations` o un ID tenant.

Altre informazioni

Per un esempio di implementazione del flusso ROPC, vedere l'esempio di codice dell'applicazione console .NET in GitHub.