Condividi tramite

Definire un profilo tecnico RESTful nei criteri personalizzati di Azure Active Directory B2C

  • Articolo

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) offre il supporto per l'integrazione del proprio servizio RESTful. Azure AD B2C invia dati al servizio RESTful in una raccolta di attestazioni di input e riceve dati in una raccolta di attestazioni di output. Per altre informazioni, vedere Integrare scambi di attestazioni API REST nei criteri personalizzati di Azure AD B2C.

Protocollo

L'attributo Nome dell'elemento Protocollo deve essere impostato su Proprietary. L'attributo gestore deve contenere il nome completo dell'assembly del gestore di protocollo usato da Azure AD B2C: Web.TPEngine.Providers.RestfulProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null.

Nell'esempio seguente viene illustrato un profilo tecnico RESTful:

<TechnicalProfile Id="REST-UserMembershipValidator">
  <DisplayName>Validate user input data and return loyaltyNumber claim</DisplayName>
  <Protocol Name="Proprietary" Handler="Web.TPEngine.Providers.RestfulProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />
  ...

Attestazioni di input

L'elemento InputClaims contiene un elenco di attestazioni da inviare all'API REST. È anche possibile eseguire il mapping del nome dell'attestazione per il nome definito nell'API REST. L'esempio seguente illustra il mapping tra i criteri e l'API REST. L'attestazione givenName viene inviata all'API REST come firstName, mentre surname viene inviato come lastName. L'attestazione messaggio di posta elettronica viene impostata così com'è.

<InputClaims>
  <InputClaim ClaimTypeReferenceId="email" />
  <InputClaim ClaimTypeReferenceId="givenName" PartnerClaimType="firstName" />
  <InputClaim ClaimTypeReferenceId="surname" PartnerClaimType="lastName" />
</InputClaims>

L'elemento InputClaimsTransformations può contenere una raccolta di elementi InputClaimsTransformation che vengono usati per modificare le attestazioni di input o per generarne di nuove prima dell'invio all'API REST.

Inviare un payload JSON

Il profilo tecnico dell'API REST consente di inviare un payload JSON complesso a un endpoint.

Per inviare un payload JSON complesso:

  1. Compilare il payload JSON con la trasformazione delle attestazioni GenerateJson .
  2. Nel profilo tecnico dell'API REST:
    1. Aggiungere una trasformazione delle attestazioni di input con un riferimento alla GenerateJson trasformazione delle attestazioni.
    2. Impostare l'opzione SendClaimsIn dei metadati su body
    3. Impostare l'opzione ClaimUsedForRequestPayload dei metadati sul nome dell'attestazione contenente il payload JSON.
    4. Nell'attestazione di input aggiungere un riferimento all'attestazione di input contenente il payload JSON.

L'esempio TechnicalProfile seguente invia un messaggio di posta elettronica di verifica usando un servizio di posta elettronica di terze parti (in questo caso SendGrid).

<TechnicalProfile Id="SendGrid">
  <DisplayName>Use SendGrid's email API to send the code to the user</DisplayName>
  <Protocol Name="Proprietary" Handler="Web.TPEngine.Providers.RestfulProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />
  <Metadata>
    <Item Key="ServiceUrl">https://api.sendgrid.com/v3/mail/send</Item>
    <Item Key="AuthenticationType">Bearer</Item>
    <Item Key="SendClaimsIn">Body</Item>
    <Item Key="ClaimUsedForRequestPayload">sendGridReqBody</Item>
    <Item Key="DefaultUserMessageIfRequestFailed">Cannot process your request right now, please try again later.</Item>
  </Metadata>
  <CryptographicKeys>
    <Key Id="BearerAuthenticationToken" StorageReferenceId="B2C_1A_SendGridApiKey" />
  </CryptographicKeys>
  <InputClaimsTransformations>
    <InputClaimsTransformation ReferenceId="GenerateSendGridRequestBody" />
  </InputClaimsTransformations>
  <InputClaims>
    <InputClaim ClaimTypeReferenceId="sendGridReqBody" />
  </InputClaims>
</TechnicalProfile>

Attestazioni di output

L'elemento OutputClaims contiene un elenco di attestazioni restituite dall'API REST. Potrebbe essere necessario eseguire il mapping del nome dell'attestazione definito nei criteri per il nome definito nell'API REST. È anche possibile includere attestazioni che non vengono restituite dall'API REST, purché si imposti 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 l'attestazione restituita dall'API REST:

  • L'attestazioneMembershipId di cui viene eseguito il mapping per il nome di attestazione loyaltyNumber.

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

  • L'attestazione loyaltyNumberIsNew con valore predefinito impostato su true.
<OutputClaims>
  <OutputClaim ClaimTypeReferenceId="loyaltyNumber" PartnerClaimType="MembershipId" />
  <OutputClaim ClaimTypeReferenceId="loyaltyNumberIsNew" DefaultValue="true" />
</OutputClaims>

Metadati UFX

Attributo Richiesto Descrizione
ServiceUrl Sì L'URL dell'endpoint API REST.
AuthenticationType Sì Tipo di autenticazione eseguita dal provider di attestazioni RESTful. Valori possibili: None, BasicBearer, ClientCertificate, o ApiKeyHeader.
  • Il None valore indica che l'API REST è anonima.
  • Il valoreBasic indica che l'API REST viene protetta con l'autenticazione di base HTTP. Solo gli utenti verificati, tra cui Azure AD B2C, possono accedere all'API.
  • Il ClientCertificate valore (consigliato) indica che l'API REST limita l'accesso usando l'autenticazione del certificato client. Solo i servizi che dispongono dei certificati appropriati, ad esempio Azure AD B2C, possono accedere all'API.
  • Il Bearer valore indica che l'API REST limita l'accesso usando il token bearer OAuth2 client.
  • Il ApiKeyHeader valore indica che l'API REST è protetta con l'intestazione HTTP della chiave API, ad esempio x-functions-key.
AllowInsecureAuthInProduction No Indica se l'oggetto AuthenticationType può essere impostato su none nell'ambiente di produzione (DeploymentMode di TrustFrameworkPolicy è impostato su Productiono non specificato). Valori possibili: true o false (impostazione predefinita).
SendClaimsIn No Specifica la modalità di invio di attestazioni di input al provider di attestazioni RESTful. Valori possibili: Body (impostazione predefinita), Form, HeaderUrl o QueryString.
Il valore Body è l'attestazione di input che viene inviata nel corpo della richiesta in formato JSON.
Il valoreForm è l'attestazione di input che viene inviata nel corpo della richiesta nel formato valore di chiave e commerciale "&" separata.
Il valoreHeader è l'attestazione di input che viene inviata nell'intestazione della richiesta.
Il Url valore è l'attestazione di input inviata nell'URL, https://api.example.com/{claim1}/{claim2}?{claim3}={claim4}ad esempio . La parte del nome host dell'URL non può contenere attestazioni.
Il valoreQueryString è l'attestazione di input che viene inviata nella stringa di query della richiesta.
I verbi HTTP richiamati da ognuno sono i seguenti:
  • Body:INSERISCI
  • Form:INSERISCI
  • Header:OTTIENI
  • Url:OTTIENI
  • QueryString:OTTIENI
ClaimsFormat No Attualmente non usato; può essere ignorato.
ClaimUsedForRequestPayload No Nome di un'attestazione stringa contenente il payload da inviare all'API REST.
DebugMode No Il profilo tecnico viene eseguito in modalità debug. Valori possibili: true o false (impostazione predefinita). In modalità debug, l'API REST può restituire altre informazioni. Vedere la sezione Restituzione del messaggio di errore.
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 resolver di attestazioni nel profilo tecnico, impostarlo 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 outputClaim impostare l'oggetto PartnerClaimType sull'elemento percorso JSON che si vuole restituire. Ad esempio: firstName.localizedo data[0].to[0].email.
UseClaimAsBearerToken No Nome dell'attestazione che contiene il token di connessione.

Gestione degli errori

I metadati seguenti possono essere usati per configurare i messaggi di errore visualizzati in caso di errore dell'API REST. I messaggi di errore possono essere localizzati.

Attributo Richiesto Descrizione
DefaultUserMessageIfRequestFailed No Messaggio di errore personalizzato predefinito per tutte le eccezioni dell'API REST.
UserMessageIfCircuitOpen No Messaggio di errore quando l'API REST non è raggiungibile. Se non specificato, verrà restituito DefaultUserMessageIfRequestFailed.
UserMessageIfDnsResolutionFailed No Messaggio di errore per l'eccezione di risoluzione DNS. Se non specificato, verrà restituito DefaultUserMessageIfRequestFailed.
UserMessageIfRequestTimeout No Messaggio di errore quando si verifica il timeout della connessione. Se non specificato, verrà restituito DefaultUserMessageIfRequestFailed.

Chiavi crittografiche

Se il tipo di autenticazione è impostato su None, l'elemento CryptographicKeys non viene usato.

<TechnicalProfile Id="REST-API-SignUp">
  <DisplayName>Validate user's input data and return loyaltyNumber claim</DisplayName>
  <Protocol Name="Proprietary" Handler="Web.TPEngine.Providers.RestfulProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />
  <Metadata>
    <Item Key="ServiceUrl">https://your-app-name.azurewebsites.NET/api/identity/signup</Item>
    <Item Key="AuthenticationType">None</Item>
    <Item Key="SendClaimsIn">Body</Item>
  </Metadata>
</TechnicalProfile>

Se il tipo di autenticazione è impostato su Basic, l'elemento CryptographicKeys contiene i seguenti attributi:

Attributo Richiesto Descrizione
BasicAuthenticationUsername Sì Il nome utente usato per l'autenticazione.
BasicAuthenticationPassword Sì La password usata per l'autenticazione.

Nell'esempio seguente viene illustrato un profilo tecnico con autenticazione di base:

<TechnicalProfile Id="REST-API-SignUp">
  <DisplayName>Validate user's input data and return loyaltyNumber claim</DisplayName>
  <Protocol Name="Proprietary" Handler="Web.TPEngine.Providers.RestfulProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />
  <Metadata>
    <Item Key="ServiceUrl">https://your-app-name.azurewebsites.NET/api/identity/signup</Item>
    <Item Key="AuthenticationType">Basic</Item>
    <Item Key="SendClaimsIn">Body</Item>
  </Metadata>
  <CryptographicKeys>
    <Key Id="BasicAuthenticationUsername" StorageReferenceId="B2C_1A_B2cRestClientId" />
    <Key Id="BasicAuthenticationPassword" StorageReferenceId="B2C_1A_B2cRestClientSecret" />
  </CryptographicKeys>
</TechnicalProfile>

Se il tipo di autenticazione è impostato su ClientCertificate, l'elemento CryptographicKeys contiene i seguenti attributi:

Attributo Richiesto Descrizione
ClientCertificate Sì Il certificato X509 (set di chiavi RSA) da usare per l'autenticazione. 
<TechnicalProfile Id="REST-API-SignUp">
  <DisplayName>Validate user's input data and return loyaltyNumber claim</DisplayName>
  <Protocol Name="Proprietary" Handler="Web.TPEngine.Providers.RestfulProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />
  <Metadata>
    <Item Key="ServiceUrl">https://your-app-name.azurewebsites.NET/api/identity/signup</Item>
    <Item Key="AuthenticationType">ClientCertificate</Item>
    <Item Key="SendClaimsIn">Body</Item>
  </Metadata>
  <CryptographicKeys>
    <Key Id="ClientCertificate" StorageReferenceId="B2C_1A_B2cRestClientCertificate" />
  </CryptographicKeys>
</TechnicalProfile>

Se il tipo di autenticazione è impostato su Bearer, l'elemento CryptographicKeys contiene i seguenti attributi:

Attributo Richiesto Descrizione
BearerAuthenticationToken No Token di connessione OAuth 2.0. 
<TechnicalProfile Id="REST-API-SignUp">
  <DisplayName>Validate user's input data and return loyaltyNumber claim</DisplayName>
  <Protocol Name="Proprietary" Handler="Web.TPEngine.Providers.RestfulProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />
  <Metadata>
    <Item Key="ServiceUrl">https://your-app-name.azurewebsites.NET/api/identity/signup</Item>
    <Item Key="AuthenticationType">Bearer</Item>
    <Item Key="SendClaimsIn">Body</Item>
  </Metadata>
  <CryptographicKeys>
    <Key Id="BearerAuthenticationToken" StorageReferenceId="B2C_1A_B2cRestClientAccessToken" />
  </CryptographicKeys>
</TechnicalProfile>

Se il tipo di autenticazione è impostato su ApiKeyHeader, l'elemento CryptographicKeys contiene i seguenti attributi:

Attributo Richiesto Descrizione
Nome dell'intestazione HTTP, ad esempio x-functions-key, o x-api-key. Sì Chiave utilizzata per l'autenticazione.

Nota

Al momento, Azure AD B2C supporta una sola intestazione HTTP per l'autenticazione. Se la chiamata RESTful richiede più intestazioni, ad esempio un ID client e un valore del segreto client, sarà necessario eseguire il proxy della richiesta in qualche modo.

<TechnicalProfile Id="REST-API-SignUp">
  <DisplayName>Validate user's input data and return loyaltyNumber claim</DisplayName>
  <Protocol Name="Proprietary" Handler="Web.TPEngine.Providers.RestfulProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />
  <Metadata>
    <Item Key="ServiceUrl">https://your-app-name.azurewebsites.NET/api/identity/signup</Item>
    <Item Key="AuthenticationType">ApiKeyHeader</Item>
    <Item Key="SendClaimsIn">Body</Item>
  </Metadata>
  <CryptographicKeys>
    <Key Id="x-functions-key" StorageReferenceId="B2C_1A_RestApiKey" />
  </CryptographicKeys>
</TechnicalProfile>

Restituzione del messaggio di errore di convalida

L'API REST può restituire un messaggio di errore, ad esempio "Utente nel sistema CRM non trovato". Se si verifica un errore, l'API REST deve restituire un messaggio di errore HTTP 4xx, ad esempio 400 (richiesta non valida) o 409 (conflitto) codice di stato della risposta. Il corpo della risposta contiene un messaggio di errore formattato in JSON:

{
  "version": "1.0.0",
  "status": 409,
  "code": "API12345",
  "requestId": "50f0bd91-2ff4-4b8f-828f-00f170519ddb",
  "userMessage": "Message for the user",
  "developerMessage": "Verbose description of problem and how to fix it.",
  "moreInfo": "https://restapi/error/API12345/moreinfo"
}
Attributo Richiesto Descrizione
Versione Sì Versione dell'API REST. Ad esempio: 1.0.1
stato Sì Un numero simile ai codici di stato della risposta HTTP e deve essere 409. Il servizio REST può restituire un codice di stato HTTP 4XX, ma il valore del status file nel corpo della risposta in formato JSON deve essere 409.
codice No Un codice di errore del provider di endpoint RESTful, visualizzato quando DebugMode è abilitato.
requestId No Un identificatore della richiesta del provider di endpoint RESTful, visualizzato quando DebugMode è abilitato.
userMessage Sì Un messaggio di errore visualizzato dall'utente.
developerMessage No La descrizione dettagliata del problema e della sua risoluzione, visualizzata quando DebugMode è abilitato.
moreInfo No Un URI che rimana alle informazioni aggiuntive, visualizzato quando DebugMode è abilitata.

L'esempio seguente illustra una classe C# che restituisce un messaggio di errore:

public class ResponseContent
{
  public string Version { get; set; }
  public int Status { get; set; }
  public string Code { get; set; }
  public string UserMessage { get; set; }
  public string DeveloperMessage { get; set; }
  public string RequestId { get; set; }
  public string MoreInfo { get; set; }
}

Passaggi successivi

Per esempi relativi all'uso di un profilo tecnico RESTful, vedere gli articoli seguenti: