Personalizzare le credenziali verificabili

Le definizioni delle credenziali verificabili sono costituite da due componenti, definizioni di visualizzazione e definizioni di regole . Una definizione di visualizzazione controlla la personalizzazione delle credenziali e dello stile delle attestazioni. Una definizione di regole determina quali utenti devono fornire prima di ricevere credenziali verificabili.

Questo articolo illustra come modificare entrambi i tipi di definizioni per soddisfare i requisiti dell'organizzazione.

Definizione di visualizzazione: oggetti visivi delle credenziali del portafoglio

ID verificato di Microsoft Entra offrire un set limitato di opzioni che possono essere usate per riflettere il tuo marchio. Questo articolo fornisce istruzioni su come personalizzare le credenziali e le procedure consigliate per la progettazione delle credenziali che hanno un aspetto ottimale dopo l'emissione agli utenti.

Microsoft Authenticator, essendo un portafoglio delle identità decentralizzate, visualizza le credenziali verificabili rilasciate agli utenti come carte. In qualità di amministratore di VC, è possibile scegliere colori, icone e stringhe di testo per il marchio dell'organizzazione.

Screenshot of a verified credential card in Authenticator, calling out key elements.

Le schede contengono anche campi personalizzabili. È possibile usare questi campi per comunicare agli utenti lo scopo della scheda, gli attributi che contiene e altro ancora.

Creare una definizione di visualizzazione delle credenziali

La definizione di visualizzazione è un semplice documento JSON che descrive come l'app wallet deve visualizzare il contenuto delle credenziali verificabili.

Nota

Questo modello di visualizzazione è attualmente utilizzato solo da Microsoft Authenticator.

La definizione di visualizzazione ha la struttura seguente. L'URI del logo, se specificato come URL, deve essere un URL disponibile pubblicamente in Internet.

{
    "locale": "en-US",
    "card": {
      "title": "Verified Credential Expert",
      "issuedBy": "Microsoft",
      "backgroundColor": "#000000",
      "textColor": "#ffffff",
      "logo": {
        "uri": "https://didcustomerplayground.blob.core.windows.net/public/VerifiedCredentialExpert_icon.png",
        "description": "Verified Credential Expert Logo"
      },
      "description": "Use your verified credential to prove to anyone that you know all about verifiable credentials."
    },
    "consent": {
      "title": "Do you want to get your Verified Credential?",
      "instructions": "Sign in with your account to get your card."
    },
    "claims": [
      {
        "claim": "vc.credentialSubject.firstName",
        "label": "First name",
        "type": "String"
      },
      {
        "claim": "vc.credentialSubject.lastName",
        "label": "Last name",
        "type": "String"
      }
    ]
}

Per altre informazioni sulle proprietà, vedere tipo displayModel.

Definizione delle regole: requisiti dell'utente

La definizione delle regole è un semplice documento JSON che descrive le proprietà importanti delle credenziali verificabili. In particolare, descrive come vengono usate le attestazioni per popolare le credenziali verificabili e il tipo di credenziale.

{
  "attestations": {
      ...
  },
  "validityInterval":  2592000,
  "vc": {
    "type": [
      "VerifiedCredentialExpert"
    ]
  }
}

Attestati

Nella definizione delle regole sono attualmente disponibili i quattro tipi di attestazione seguenti. Sono diversi modi per fornire attestazioni usate dal ID verificato di Microsoft Entra servizio emittente da inserire in una credenziale verificabile e attestare tali informazioni con l'identificatore decentralizzato (DID). Nella definizione delle regole è possibile usare più tipi di attestazione.

  • Token ID: quando questa opzione è configurata, è necessario fornire un URI di configurazione openID Connessione e includere le attestazioni che devono essere incluse nelle credenziali verificabili. Agli utenti viene richiesto di accedere all'app Authenticator per soddisfare questo requisito e aggiungere le attestazioni associate dal proprio account. Per configurare questa opzione, vedere questa guida

  • Hint per il token ID: l'app e l'esercitazione di esempio usano l'hint per il token ID. Quando questa opzione è configurata, l'app relying party dovrà fornire attestazioni che devono essere incluse nelle credenziali verificabili nella richiesta di rilascio dell'API del servizio di richiesta. Dove l'app relying party ottiene le attestazioni dall'app, ma può provenire dalla sessione di accesso corrente, dai sistemi CRM back-end o anche dall'input dell'utente autocertidata. Per configurare questa opzione, vedere questa guida

  • Credenziali verificabili: il risultato finale di un flusso di rilascio consiste nel produrre credenziali verificabili, ma è anche possibile chiedere all'utente di presentare una credenziale verificabile per rilasciare una credenziale. La definizione delle regole è in grado di accettare attestazioni specifiche dalle credenziali verificabili presentate e includere tali attestazioni nelle credenziali verificabili appena rilasciate dall'organizzazione. Per configurare questa opzione, vedere questa guida

  • Attestazioni autocertificate: quando questa opzione è selezionata, l'utente può digitare le informazioni direttamente in Authenticator. Al momento, le stringhe sono l'unico input supportato per le attestazioni autocertificate. Per configurare questa opzione, vedere questa guida

Per altre informazioni sul modello JSON delle regole, vedere rulesModel type (Tipo rulesModel).

Tipi di credenziale

Tutte le credenziali verificabili devono dichiarare il tipo nella definizione delle regole. Il tipo di credenziale distingue uno schema di credenziali verificabile da altre credenziali e garantisce l'interoperabilità tra autorità emittenti e verificatori. Per indicare un tipo di credenziale, specificare uno o più tipi di credenziali soddisfatti dalla credenziale. Ogni tipo è rappresentato da una stringa univoca. Spesso, viene usato un URI per garantire l'univocità globale. L'URI non deve essere indirizzabile. Viene trattato come stringa. Ad esempio, una credenziale di diploma rilasciata da Contoso University potrebbe dichiarare i tipi seguenti:

Type Scopo
https://schema.org/EducationalCredential Dichiara che i diploma rilasciati da Contoso University contengono attributi definiti dall'oggetto schema.org EducationaCredential .
https://schemas.ed.gov/universityDiploma2020 Dichiara che i diploma rilasciati da Contoso University contengono attributi definiti dal Dipartimento dell'Istruzione degli Stati Uniti.
https://schemas.contoso.edu/diploma2020 Dichiara che i diploma rilasciati da Contoso University contengono attributi definiti da Contoso University.

Dichiarando tre tipi di diploma, Contoso può rilasciare credenziali che soddisfano richieste diverse dai verificatori. Una banca può richiedere un set di EducationCredentials da un utente e il diploma può essere utilizzato per soddisfare la richiesta. In alternativa, l'associazione degli ex-studenti contoso può richiedere una credenziale di tipo https://schemas.contoso.edu/diploma2020e il diploma può soddisfare la richiesta.

Per garantire l'interoperabilità delle credenziali, è consigliabile collaborare strettamente con le organizzazioni correlate per definire tipi di credenziali, schemi e URI da usare nel settore. Molti organismi del settore forniscono indicazioni sulla struttura dei documenti ufficiali che possono essere riutilizzati per definire il contenuto delle credenziali verificabili. È anche consigliabile collaborare con i verificatori delle credenziali per comprendere come intendono richiedere e utilizzare le credenziali verificabili.

Passaggi successivi

Ora che si ha una migliore comprensione della progettazione delle credenziali verificabili e di come creare credenziali personalizzate, vedere: