Definire un profilo tecnico OAuth2 in un criterio personalizzato di Azure Active Directory B2C

Nota

In Azure Active Directory B2C i criteri personalizzati sono stati progettati principalmente per far fronte a scenari complessi. Per la maggior parte degli scenari, è consigliabile usare i flussi utente predefiniti. In caso contrario, vedere Introduzione ai criteri personalizzati in Active Directory B2C.

Azure Active Directory B2C (Azure AD B2C) fornisce supporto per il provider di identità del protocollo OAuth2. OAuth2 è il protocollo primario per l'autorizzazione e l'autenticazione delegata. Per altre informazioni, vedere la RFC 6749 The OAuth 2.0 Authorization Framework. Con un profilo tecnico OAuth2, è possibile eseguire la federazione con un provider di identità basato su OAuth2, ad esempio Facebook. La federazione con un provider di identità consente agli utenti di accedere con le identità aziendali o di social networking esistenti.

Protocollo

L'attributo Nome dell'elemento Protocollo deve essere impostato su OAuth2. Ad esempio, il protocollo per il profilo tecnico Facebook-OAUTH è OAuth2:

<TechnicalProfile Id="Facebook-OAUTH">
  <DisplayName>Facebook</DisplayName>
  <Protocol Name="OAuth2" />
  ...

Attestazioni di input

Gli elementi InputClaims e InputClaimsTransformations non sono obbligatori. È tuttavia consigliabile inviare altri parametri al provider di identità. L'esempio seguente aggiunge il parametro della stringa di query domain_hint e il valore di contoso.com alla richiesta di autorizzazione.

<InputClaims>
  <InputClaim ClaimTypeReferenceId="domain_hint" DefaultValue="contoso.com" />
</InputClaims>

Attestazioni di output

L'elemento OutputClaims contiene un elenco di attestazioni restituite dal provider di identità OAuth2. Può essere necessario eseguire il mapping del nome dell'attestazione definito nei criteri per il nome definito nel provider di identità. È anche possibile includere le attestazioni che non vengono restituite dal provider di identità, purché sia impostato l'attributo DefaultValue.

L'elemento OutputClaimsTransformations può contenere una raccolta di elementi OutputClaimsTransformation che vengono usati per modificare le attestazioni di output o per generarne di nuove.

L'esempio seguente illustra le attestazioni restituite dal provider di identità Facebook:

  • Il mapping dell'attestazione first_name viene eseguito per l'attestazione givenName.
  • Il mapping dell'attestazione last_name viene eseguito per l'attestazione surname.
  • Attestazione displayName senza mapping dei nomi.
  • L'attestazione email senza eseguire il mapping del nome.

Il profilo tecnico restituisce anche le attestazioni che non vengono restituite dal provider di identità:

  • L'attestazione identityProvider che contiene il nome del provider di identità.
  • L'attestazione authenticationSource con un valore predefinito di socialIdpAuthentication.
<OutputClaims>
  <OutputClaim ClaimTypeReferenceId="issuerUserId" PartnerClaimType="id" />
  <OutputClaim ClaimTypeReferenceId="givenName" PartnerClaimType="first_name" />
  <OutputClaim ClaimTypeReferenceId="surname" PartnerClaimType="last_name" />
  <OutputClaim ClaimTypeReferenceId="displayName" PartnerClaimType="name" />
  <OutputClaim ClaimTypeReferenceId="email" PartnerClaimType="email" />
  <OutputClaim ClaimTypeReferenceId="identityProvider" DefaultValue="facebook.com" />
  <OutputClaim ClaimTypeReferenceId="authenticationSource" DefaultValue="socialIdpAuthentication" />
</OutputClaims>

Metadati dell'endpoint di autorizzazione

Il flusso di autorizzazione inizia quando Azure AD B2C indirizza l'utente all'endpoint dei provider di /authorize identità OAuth2. La chiamata all'endpoint di autorizzazione è la parte interattiva del flusso, in cui l'utente esegue l'azione. A questo punto, all'utente viene richiesto di completare l'accesso nel provider di identità OAuth2. Ad esempio, immettendo il nome utente e la password.

Azure AD B2C crea una richiesta di autorizzazione fornendo l'ID client, gli ambiti, l'URI di reindirizzamento e altri parametri necessari per acquisire un token di accesso dal provider di identità. Questa sezione descrive i metadati dell'endpoint di autorizzazione, che consente di configurare la richiesta all'endpoint /authorize del provider di identità.

La richiesta all'endpoint di autorizzazione è sempre HTTP GET. Nell'esempio seguente viene illustrata una chiamata all'endpoint di autorizzazione.

GET https://login.contoso.com/oauth/v2/authorization?
client_id=12345
&response_type=code
&response_mode=query
&redirect_uri=urn%3Aietf%3Awg%3Aoauth%3A2.0%3Aoob
&scope=profile%20offline_access
&redirect_uri=https%3a%2f%2fabrikam.b2clogin.com%2fabrikam.onmicrosoft.com%2foauth2%2fauthresp
&state=...

Nella tabella seguente sono elencati i metadati dell'endpoint di autorizzazione.

Attributo Obbligatoria Descrizione
authorization_endpoint L'URL dell'endpoint di autorizzazione come per RFC 6749.
client_id L'identificatore dell'attestazione del provider di identità.
AdditionalRequestQueryParameters No Parametri di query di richiesta aggiuntivi. Ad esempio, è possibile inviare parametri aggiuntivi al provider di identità. È possibile includere più parametri usando la virgola di delimitazione.
response_mode No Il metodo che usa il provider di identità per restituire il risultato ad Azure AD B2C. I valori possibili sono: query, form_post (impostazione predefinita), o fragment.
scope No Ambito della richiesta definita in base alla specifica del provider di identità OAuth2. Ad esempio openid, profile, e email.
UsePolicyInRedirectUri No Indica se usare un criterio durante la costruzione dell'URI di reindirizzamento. Quando si configura l'applicazione nel provider di identità, è necessario specificare l'URI di reindirizzamento. L'URI di reindirizzamento punta ad Azure AD B2C, https://{your-tenant-name}.b2clogin.com/{your-tenant-name}.onmicrosoft.com/oauth2/authresp. Se si specifica true, è necessario aggiungere un URI di reindirizzamento per ogni criterio usato. Ad esempio: https://{your-tenant-name}.b2clogin.com/{your-tenant-name}.onmicrosoft.com/{policy-name}/oauth2/authresp.

Metadati dell'endpoint del token

Dopo che l'utente ha completato l'autenticazione nell'endpoint di autorizzazione del provider di identità, viene restituita una risposta contenente l'autorizzazione code ad Azure AD B2C. Azure AD B2C riscatta il codice di autorizzazione per un token di accesso inviando una richiesta POST all'endpoint /token del provider di identità. Questa sezione descrive i metadati dell'endpoint del token, che consente di configurare la richiesta all'endpoint /token del provider di identità.

La richiesta HTTP seguente mostra una chiamata di Azure AD B2C all'endpoint del token del provider di identità.

POST https://contoso/oauth2/token 
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&client_id=12345&scope=profile offline_access&code=AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq... 

Nella tabella seguente sono elencati i metadati dell'endpoint del token.

Attributo Obbligatoria Descrizione
AccessTokenEndpoint URL dell'endpoint del token. Ad esempio, https://www.linkedin.com/oauth/v2/accessToken.
HttpBinding No Associazione HTTP prevista all'endpoint del token. I valori possibili sono: GET o POST.
AccessTokenResponseFormat No Il formato delle chiamate a endpoint del token di accesso. Ad esempio, Facebook richiede un metodo HTTP GET, ma la risposta del token di accesso è in formato JSON. Valori possibili: Default, Jsone JsonP.
ExtraParamsInAccessTokenEndpointResponse No Contiene altri parametri che possono essere restituiti nella risposta di AccessTokenEndpoint da alcuni provider di identità. Ad esempio, la risposta di AccessTokenEndpoint contiene un altro parametro, ad esempio openid, ovvero un parametro obbligatorio oltre all'access_token in una stringa di query della richiesta ClaimsEndpoint. Più nomi di parametro devono essere preceduti dal carattere di escape e separati da una virgola di delimitazione ','.
token_endpoint_auth_method No Specifica il modo in cui Azure AD B2C invia l'intestazione di autenticazione all'endpoint del token. Valori possibili: client_secret_post (impostazione predefinita) e client_secret_basic, private_key_jwt. Per altre informazioni, vedere la sezione Autenticazione client OpenID Connect.
token_signing_algorithm No Specifica l'algoritmo di firma da utilizzare quando token_endpoint_auth_method è impostato su private_key_jwt. Valori possibili: RS256 (impostazione predefinita) o RS512.

Configurare il metodo di associazione HTTP

Per impostazione predefinita, la richiesta all'endpoint del token usa HTTP POST.

<Item Key="AccessTokenEndpoint">https://contoso.com/oauth2/token</Item>
<Item Key="HttpBinding">POST</Item>

La chiamata HTTP seguente illustra una chiamata all'endpoint del token usando la richiesta HTTP POST:

POST /oauth2/token

client_id=abcd&client_secret=1234&redirect_uri=https%3a%2f%2fcontoso.b2clogin.com%2fcontoso.onmicrosoft.com%2foauth2%2fauthresp&code=12345&grant_type=authorization_code

Per i provider di identità che richiedono l'uso del metodo HTTP GET nell'endpoint /token , impostare i HttpBinding metadati su GET. Si noti che, nell'esempio seguente, è AccessTokenResponseFormat impostato su json, poiché l'endpoint del token restituisce la risposta in formato JSON.

<Item Key="AccessTokenEndpoint">https://contoso.com/oauth2/token</Item>
<Item Key="HttpBinding">GET</Item>
<Item Key="AccessTokenResponseFormat">json</Item>
GET /oauth2/token?client_id=abcd&client_secret=1234&redirect_uri=https%3a%2f%2fcontoso.b2clogin.com%2fcontoso.onmicrosoft.com%2foauth2%2fauthresp&code=12345&grant_type=authorization_code

Configurare il formato di risposta del token di accesso

Per i provider di identità che supportano il metodo HTTP POST, l'oggetto AccessTokenResponseFormat è impostato per impostazione predefinita su json. Se il provider di identità supporta la richiesta HTTP GET, è necessario impostare il formato di risposta del token di accesso in json modo esplicito.

<Item Key="AccessTokenEndpoint">https://contoso.com/oauth2/token</Item>
<Item Key="HttpBinding">GET</Item>
<Item Key="AccessTokenResponseFormat">json</Item>

Nell'esempio seguente viene illustrata una risposta dell'endpoint token in formato JSON:

{
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6IlBFcG5...",
    "token_type": "Bearer",
    "not_before": 1637924390,
    "expires_in": 960000,
}

Configurare il metodo di autenticazione

Le richieste all'endpoint del token richiedono sempre l'autenticazione. Per impostazione predefinita, Azure AD B2C fornisce al provider di identità le credenziali client. Per impostazione predefinita, il metodo di autenticazione è client_secret_post, incluse le credenziali client (client_id e client_secret) nel corpo della richiesta.

La richiesta HTTP seguente all'endpoint del token contiene e client_id i client_secret dati POST. Per le richieste client_id GET e gli client_secret elementi sono inclusi nei parametri della stringa di query.

POST /oauth2/token

client_id=abcd&client_secret=1234&redirect_uri=https%3a%2f%2fcontoso.b2clogin.com%2fcontoso.onmicrosoft.com%2foauth2%2fauthresp&code=12345&grant_type=authorization_code

Per i provider di identità che richiedono l'uso dell'autenticazione di base HTTP nell'endpoint /token , configurare i token_endpoint_auth_method metadati in client_secret_basic. Con questo tipo di metodo di autenticazione, le credenziali client vengono passate al provider di identità usando lo schema di autenticazione HTTP Basic.

<Item Key="AccessTokenEndpoint">https://contoso.com/oauth2/token</Item>
<Item Key="token_endpoint_auth_method">client_secret_basic</Item>

La richiesta HTTP seguente illustra una chiamata all'endpoint del token con l'autenticazione di base HTTP. L'intestazione di autorizzazione contiene l'ID client e il segreto client, nel formato client_ID:client_secret, con codifica base64.

POST /oauth2/token

Authorization: Basic YWJjZDoxMjM0

redirect_uri=https%3a%2f%2fcontoso.b2clogin.com%2fontoso.onmicrosoft.com%2foauth2%2fauthresp&code=12345&grant_type=authorization_code

Per i provider di identità che supportano l'autenticazione JWT della chiave privata, configurare i token_endpoint_auth_method metadati in private_key_jwt. Con questo tipo di metodo di autenticazione, il certificato fornito ad Azure AD B2C viene usato per generare un'asserzione firmata, passata al provider di identità tramite il client_assertion parametro . Impostato client_assertion_type su urn:ietf:params:oauth:client-assertion-type:jwt-bearer. I token_signing_algorithm metadati specificano l'algoritmo di firma del token JWT.

<Item Key="AccessTokenEndpoint">https://contoso.com/oauth2/token</Item>
<Item Key="token_endpoint_auth_method">private_key_jwt</Item>
<Item Key="token_signing_algorithm">RS256</Item>

La richiesta HTTP seguente illustra una chiamata all'endpoint del token usando l'autenticazione JWT della chiave privata.

POST /oauth2/token

client_assertion=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiIsImtpZCI6IjJFRFg0dWRYeDIxbXNoaXdJVzczMUY3OUZSbFJiUDZXVXJyZmktR1RFeVkifQ.eyJpc3MiOiJhYmNkIiwiZXhwIjoxNjM3OTI5ODY0LCJuYmYiOjE2Mzc5Mjk1NjQsImF1ZCI6Imh0dHBzOi8vNWRlNC0xMDktNjQtMTI0LTUzLm5ncm9rLmlvL2FjY2Vzc190b2tlbiIsImp0aSI6IjVxQWlGV2lEODNDbU1KWWNrejBRdGc9PSIsInN1YiI6ImFiY2QiLCJpYXQiOjE2Mzc5Mjk1NjR9.C4OtRnrLaQatpT5LP45O5Nb418S4v8yZi_C42ld440w&client_id=abcd&client_assertion_type=urn%3aietf%3aparams%3aoauth%3aclient-assertion-type%3ajwt-bearer&redirect_uri=https%3a%2f%2fcontoso.b2clogin.com%2fcontoso.onmicrosoft.com%2foauth2%2fauthresp&code=12345&grant_type=authorization_code

Metadati dell'endpoint delle informazioni utente

Dopo che Azure AD B2C ottiene il token di accesso dal provider di identità OAuth2, effettua una chiamata all'endpoint informazioni utente. L'endpoint delle informazioni utente, noto anche come endpoint delle attestazioni, è progettato per recuperare le attestazioni sull'utente autenticato. Azure AD B2C usa l'autenticazione del token di connessione per eseguire l'autenticazione all'endpoint delle informazioni utente dei provider di identità. Il token di connessione è il token di accesso ottenuto da Azure AD B2C dall'endpoint dei provider di /token identità.

La richiesta all'endpoint informazioni utente è sempre HTTP GET. Il token di accesso viene inviato in un parametro stringa di query denominato access_token. La richiesta HTTP seguente mostra una chiamata all'endpoint informazioni utente con il token di accesso nel parametro stringa di query.

GET /oauth2/claims?access_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6IlBFcG5... 

Nella tabella seguente sono elencati i metadati dell'endpoint delle informazioni utente.

Attributo Obbligatoria Descrizione
ClaimsEndpoint L'URL dell'endpoint di informazioni per l'utente. Ad esempio, https://api.linkedin.com/v2/me.
ClaimsEndpointAccessTokenName No Il nome del parametro della stringa di query del token di accesso. Valore predefinito: access_token.
ClaimsEndpointFormatName No Il nome del parametro della stringa di query di formato. Ad esempio, è possibile impostare il nome come format in questo endpoint attestazioni LinkedInhttps://api.linkedin.com/v1/people/~?format=json.
ClaimsEndpointFormat No Il valore del parametro della stringa di query di formato. Ad esempio, è possibile impostare il valore su json in questo endpoint attestazioni LinkedIn https://api.linkedin.com/v1/people/~?format=json.
BearerTokenTransmissionMethod No Specifica il modo in cui viene inviato il token. Il metodo predefinito è una stringa di query. Per inviare il token come intestazione di richiesta, impostare su AuthorizationHeader.
ExtraParamsInClaimsEndpointRequest No Contiene altri parametri che possono essere restituiti nella richiesta ClaimsEndpoint da alcuni provider di identità. Più nomi di parametro devono essere preceduti dal carattere di escape e separati da una virgola di delimitazione ','.

Configurare il parametro della stringa di query del token di accesso

L'endpoint informazioni utente può richiedere l'invio del token di accesso in un determinato parametro stringa di query. Per modificare il nome del parametro stringa di query, che contiene il token di accesso, usare i ClaimsEndpointAccessTokenName metadati. Nell'esempio seguente il parametro stringa di query del token di accesso è impostato su token.

<Item Key="ClaimsEndpoint">https://contoso.com/oauth2/claims</Item>
<Item Key="ClaimsEndpointAccessTokenName">token</Item>

La chiamata HTTP seguente illustra una chiamata all'endpoint informazioni utente con ClaimsEndpointAccessTokenName impostato su token:

GET /oauth2/claims?token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6IlBFcG5...

Configurare il formato delle attestazioni

ClaimsEndpointFormat E ClaimsEndpointFormatName consente di inviare un parametro stringa di query di coppia chiave-valore all'endpoint informazioni utente. Nell'esempio seguente viene configurato un parametro stringa di query denominato format, con il valore di json.

<Item Key="ClaimsEndpoint">https://contoso.com/oauth2/claims</Item>
<Item Key="ClaimsEndpointFormatName">format</Item>
<Item Key="ClaimsEndpointFormat">json</Item>

La richiesta HTTP seguente illustra una chiamata all'endpoint informazioni utente con ClaimsEndpointFormatName e ClaimsEndpointFormat configurata.

GET /oauth2/claims?format=json&access_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6IlBFcG5...

Configurare il metodo di trasmissione del token di connessione

Per impostazione predefinita, il token di accesso viene inviato all'endpoint delle informazioni utente dei provider di identità tramite un parametro stringa di query. Per inviare il token all'interno dell'intestazione HTTP Authorization , impostare BearerTokenTransmissionMethod i metadati su AuthorizationHeader.

<Item Key="ClaimsEndpoint">https://contoso.com/oauth2/claims</Item>
<Item Key="BearerTokenTransmissionMethod">AuthorizationHeader</Item>

La richiesta HTTP seguente illustra come viene passato il token di accesso quando BearerTokenTransmissionMethod è impostato su AuthorizationHeader.

GET /oauth2/claims

Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6IlBFcG5...

Passare i parametri restituiti dall'endpoint del token

Alcuni provider di identità richiedono di passare parametri aggiuntivi restituiti dall'endpoint del token all'endpoint delle informazioni utente. Ad esempio, la risposta dall'endpoint del token contiene un parametro denominato resource, che è un parametro obbligatorio dell'endpoint informazioni utente (oltre al token di accesso). Usare i ExtraParamsInClaimsEndpointRequest metadati per specificare eventuali parametri aggiuntivi da passare. Più nomi di parametro devono essere preceduti dal carattere di escape e separati da una virgola di delimitazione ','.

Il codice JSON seguente illustra un payload JSON restituito dall'endpoint del token con un parametro denominato resource.

{
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6IlBFcG5...",
    "token_type": "Bearer",
    "not_before": 1549647431,
    "expires_in": 960000,
    "resource": "f2a76e08-93f2-4350-833c-965c02483b11"
}

Per passare il parametro all'endpoint resource informazioni utente, aggiungere i metadati seguenti:

<Item Key="ExtraParamsInClaimsEndpointRequest">resource</Item>

La richiesta HTTP seguente illustra come il resource parametro viene passato all'endpoint delle informazioni utente.

GET /oauth2/claims?resource=f2a76e08-93f2-4350-833c-965c02483b11&access_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6IlBFcG5...

Endpoint sessione finale

Per disconnettere l'utente dall'applicazione, reindirizzare l'utente all'endpoint di disconnessione di Azure AD B2C (per OAuth2 e OpenID Connect) o inviare un LogoutRequest (per SAML). Azure AD B2C cancella la sessione dell'utente dal browser. Dopo una richiesta di disconnessione, Azure AD B2C tenta di disconnettersi da tutti i provider di identità federati che l'utente può aver eseguito l'accesso. L'URI di disconnessione del provider di identità OAuth2 è configurato nei end_session_endpoint metadati. Quando l'utente si disconnette dall'applicazione tramite Azure AD B2C, verrà creato un iframe nascosto che chiamerà nella end_session_endpoint pagina di disconnessa azure AD B2C.

Nella tabella seguente sono elencati i metadati dell'endpoint delle informazioni utente.

Attributo Obbligatoria Descrizione
end_session_endpoint URL dell'endpoint della sessione finale come per RFC 6749.
SingleLogoutEnabled No Indica se durante l'accesso il profilo tecnico tenta di disconnettersi dai provider di identità federati. Per altre informazioni, vedere Disconnessa sessione di Azure AD B2C. Valori possibili: true (impostazione predefinita) o false.

Metadati generici OAuth2

Nella tabella seguente sono elencati i metadati generici del provider di identità OAuth2. I metadati descrivono come il profilo tecnico OAuth2 gestisce la convalida dei token, ottenere le attestazioni e reagire ai messaggi di errore.

Attributo Obbligatoria Descrizione
IdTokenAudience No I destinatari dell'id_token. Se specificato, Azure AD B2C controlla se il token è in un'attestazione restituita dal provider di identità ed è uguale a quello specificato.
ProviderName No Il nome del provider di identità.
ResponseErrorCodeParamName No Il nome del parametro che contiene il messaggio di errore restituito nel messaggio HTTP 200 (Ok).
IncludeClaimResolvingInClaimsHandling   No Per le attestazioni di input e output, specifica se la risoluzione delle attestazioni è inclusa nel profilo tecnico. Valori possibili: true o false (impostazione predefinita). Se si vuole usare un sistema di risoluzione delle attestazioni nel profilo tecnico, impostare questa opzione su true.
ResolveJsonPathsInJsonTokens No Indica se il profilo tecnico risolve i percorsi JSON. Valori possibili: true o false (impostazione predefinita). Usare questi metadati per leggere i dati da un elemento JSON annidato. In un outputClaim impostare l'oggetto sull'elemento PartnerClaimType del percorso JSON da restituire. Ad esempio: firstName.localizedo data[0].to[0].email.

Chiavi di crittografia

L'elemento CryptographicKeys contiene l'attributo seguente:

Attributo Obbligatoria Descrizione
client_secret Il segreto client dell'applicazione del provider di identità. La chiave di crittografia è necessaria solo se i metadati response_type sono impostati su code. In questo caso, Azure AD B2C effettua un'altra chiamata per scambiare il codice di autorizzazione per un token di accesso. Se i metadati sono impostati su id_token, è possibile omettere la chiave crittografica.
assertion_signing_key No Quando i token_endpoint_auth_method metadati sono impostati su private_key_jwt, specificare un certificato X509 da usare per firmare la chiave JWT. Questa chiave deve essere fornita dal provider di identità OAuth2.

URI di reindirizzamento

Quando si configura l'URI di reindirizzamento del provider di identità, immettere https://{tenant-name}.b2clogin.com/{tenant-name}.onmicrosoft.com/oauth2/authresp. Assicurarsi di sostituire {tenant-name} con il nome del tenant, ad esempio contosob2c. L'URI di reindirizzamento deve essere tutto minuscolo.

Passaggi successivi