Rilasciare credenziali ID verificato di Microsoft Entra da un'applicazione

Articolo
12/13/2024

In questa esercitazione si esegue un'applicazione di esempio dal computer locale che si connette al tenant di Microsoft Entra. Usando l'applicazione, si eseguirà un problema e si verificherà una scheda di esperti di credenziali verificata.

In questo articolo vengono illustrate le operazioni seguenti:

Creare la scheda di esperti di credenziali verificata in Azure.
Raccogliere le credenziali e i dettagli dell'ambiente per configurare l'applicazione di esempio.
Scaricare il codice dell'applicazione di esempio nel computer locale.
Aggiornare l'applicazione di esempio con la scheda e i dettagli dell'ambiente verificati dell'esperto di credenziali.
Eseguire l'applicazione di esempio ed eseguire la prima scheda di esperti di credenziali verificata.
Verificare la scheda dell'esperto di credenziali verificate.

Il diagramma seguente illustra l'architettura ID verificato di Microsoft Entra e il componente configurato.

Diagramma che illustra l'architettura ID verificato di Microsoft Entra.

Prerequisiti

Configurare un tenant per l'ID verificato di Microsoft Entra.
Per clonare il repository che ospita l'app di esempio, installare GIT.
Visual Studio Code, Visual Studio o un editor di codice simile.
.NET 7.0.
Scaricare ngrok e registrarsi per ottenere un account gratuito. Se non è possibile usare ngrok nell'organizzazione, leggere queste domande frequenti.
Un dispositivo mobile con la versione più recente di Microsoft Authenticator.

Creare la scheda di esperti di credenziali verificata in Azure

Suggerimento

La procedura descritta in questo articolo può variare leggermente in base al portale di partenza.

In questo passaggio si crea la scheda di esperti di credenziali verificata usando ID verificato di Microsoft Entra. Dopo aver creato le credenziali, il tenant di Microsoft Entra può rilasciarlo agli utenti che avviano il processo.

Accedi all'Interfaccia di amministrazione di Microsoft Entra come Amministratore globale.
Selezionare Credenziali verificabili.
Dopo aver configurato il tenant, verrà visualizzata la casella Crea credenziali . In alternativa, è possibile selezionare Credenziali nel menu a sinistra e selezionare + Aggiungi credenziali.

In Crea credenziali, seleziona credenziali personalizzate e seleziona Avanti:

Per Nome credenziali immettere VerifiedCredentialExpert. Questo nome viene usato nel portale per identificare le credenziali verificabili. È incluso come parte del contratto di credenziali verificabile.

Copiare il codice JSON seguente e incollarlo nella casella di testo Visualizza definizione

{
    "locale": "en-US",
    "card": {
      "title": "Verified Credential Expert",
      "issuedBy": "Microsoft",
      "backgroundColor": "#000000",
      "textColor": "#ffffff",
      "logo": {
        "uri": "https://didcustomerplayground.z13.web.core.windows.net/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"
      }
    ]
}

Copiare il codice JSON seguente e incollarlo nella casella di testo Rules definition (Definizione regole)

{
  "attestations": {
    "idTokenHints": [
      {
        "mapping": [
          {
            "outputClaim": "firstName",
            "required": true,
            "inputClaim": "$.given_name",
            "indexed": false
          },
          {
            "outputClaim": "lastName",
            "required": true,
            "inputClaim": "$.family_name",
            "indexed": true
          }
        ],
        "required": false
      }
    ]
  },
  "validityInterval": 2592000,
  "vc": {
    "type": [
      "VerifiedCredentialExpert"
    ]
  }
}

Seleziona Crea.

Lo screenshot seguente illustra come creare una nuova credenziale:

Screenshot che mostra come creare una nuova credenziale.

Raccogliere le credenziali e i dettagli dell'ambiente

Ora che si dispone di una nuova credenziale, si raccoglieranno alcune informazioni sull'ambiente e le credenziali create. Queste informazioni vengono usate quando si configura l'applicazione di esempio.

In Credenziali verificabili selezionare Rilascia credenziali.
Copiare l'autorità, ovvero l'identificatore decentralizzato, e registrarlo per un secondo momento.
Copiare l'URL del manifesto . È l'URL valutato da Authenticator prima che venga visualizzato ai requisiti di rilascio delle credenziali verificabili dall'utente. Registrarlo per usarlo in un secondo momento.
Copiare l'ID tenant e registrarlo per un secondo momento. L'ID tenant è il GUID nell'URL del manifesto evidenziato in rosso sopra.

Scaricare il codice di esempio

L'applicazione di esempio è disponibile in .NET e il codice viene gestito in un repository GitHub. Scaricare il codice di esempio da GitHub o clonare il repository nel computer locale:

git clone https://github.com/Azure-Samples/active-directory-verifiable-credentials-dotnet.git

Configurare l'app delle credenziali verificabili

Creare un segreto client per l'applicazione registrata creata. L'applicazione di esempio usa il segreto client per dimostrare la propria identità al momento della richiesta dei token.

Accedi all'Interfaccia di amministrazione di Microsoft Entra come Amministratore globale.
Selezionare Microsoft Entra ID.
Passare alla pagina Applicazioni> Registrazioni app.
Selezionare l'applicazione verifiable-credentials-app creata in precedenza.
Selezionare il nome da inserire nei dettagli di registrazione.
Copiare l'ID applicazione (client) e archiviarlo per un secondo momento.
Dal menu principale, in Gestisci, selezionare Certificati e segreti.
Selezionare Nuovo segreto client ed eseguire le operazioni seguenti:
1. In Descrizione immettere una descrizione per il segreto client, ad esempio vc-sample-secret.
2. In Scadenza selezionare la durata di validità del segreto, ad esempio sei mesi. Selezionare Aggiungi.
3. Registrare il Valore del segreto. Questo valore verrà usato per la configurazione in un passaggio successivo. Il valore del segreto non verrà visualizzato di nuovo e non sarà recuperabile da altri mezzi. Registrarlo non appena è visibile.

A questo punto, è necessario avere tutte le informazioni necessarie per configurare l'applicazione di esempio.

Aggiornare l'applicazione di esempio

Ora si apportano modifiche al codice dell'emittente dell'app di esempio per aggiornarlo con l'URL delle credenziali verificabile. Questo passaggio consente di rilasciare credenziali verificabili usando il proprio tenant.

Nella cartella active-directory-verificaable-credentials-dotnet-main aprire Visual Studio Code e selezionare il progetto all'interno della cartella 1-asp-net-core-api-idtokenhint.
Nella cartella radice del progetto aprire il file appsettings.json . Questo file contiene informazioni sull'ambiente ID verificato di Microsoft Entra. Aggiornare le proprietà seguenti con le informazioni registrate nei passaggi precedenti:
1. ID tenant: ID tenant
2. ID client: ID client
3. Segreto client: segreto client
4. DidAuthority: identificatore decentralizzato
5. Manifesto delle credenziali: URL del manifesto
CredentialType è necessario solo per la presentazione, quindi se tutto quello che si vuole fare è il rilascio, non è strettamente necessario.
Salvare il file appsettings.json.

Il codice JSON seguente illustra un file completo appsettings.json :

{
  "VerifiedID": {
    "Endpoint": "https://verifiedid.did.msidentity.com/v1.0/verifiableCredentials/",
    "VCServiceScope": "3db474b9-6a0c-4840-96ac-1fceb342124f/.default",
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "aaaabbbb-0000-cccc-1111-dddd2222eeee",
    "ClientId": "00001111-aaaa-2222-bbbb-3333cccc4444",
    "ClientSecret": "123456789012345678901234567890",
    "CertificateName": "[Or instead of client secret: Enter here the name of a certificate (from the user cert store) as registered with your application]",
    "DidAuthority": "did:web:...your-decentralized-identifier...",
    "CredentialType": "VerifiedCredentialExpert",
    "CredentialManifest":  "https://verifiedid.did.msidentity.com/v1.0/00001111-aaaa-2222-bbbb-3333cccc4444/verifiableCredentials/contracts/VerifiedCredentialExpert"
  }
}

Rilasciare la prima scheda di esperti di credenziali verificate

A questo punto è possibile rilasciare la prima scheda di esperti di credenziali verificate eseguendo l'applicazione di esempio.

Da Visual Studio Code, eseguire il progetto Verifiable_credentials_DotNet. In alternativa, dalla riga di comando del sistema operativo eseguire:

cd active-directory-verifiable-credentials-dotnet\1-asp-net-core-api-idtokenhint
dotnet build "AspNetCoreVerifiableCredentials.csproj" -c Debug -o .\bin\Debug\net6.
dotnet run

In un'altra finestra del prompt dei comandi eseguire il comando seguente. Questo comando esegue ngrok per configurare un URL su 5000 e renderlo disponibile pubblicamente su Internet.
```
ngrok http 5000
```
Nota

In alcuni computer potrebbe essere necessario eseguire il comando in questo formato: ./ngrok http 5000.
Aprire l'URL HTTPS generato da ngrok.
Da un Web browser selezionare Recupera credenziali.
Usando il dispositivo mobile, analizzare il codice a matrice con l'app Authenticator. Per altre informazioni sull'analisi del codice a matrice, vedi la sezione domande frequenti .
A questo punto, viene visualizzato un messaggio di avviso che indica che l'app o il sito Web potrebbe essere rischioso. Seleziona Avanzate.
Nell'avviso del sito Web rischioso, selezionare Continua comunque (non sicuro). Questo avviso viene visualizzato perché il dominio non è collegato all'identificatore decentralizzato (DID). Per verificare il dominio, seguire Collegare il dominio all'identificatore decentralizzato (DID). Per questa esercitazione, è possibile ignorare la registrazione del dominio e selezionare Continua comunque (non sicuro).
Viene richiesto di inserire un codice PIN visualizzato nella schermata in cui è stato scansionato il codice QR. Il PIN aggiunge un ulteriore livello di protezione al rilascio. Il codice PIN viene generato in modo casuale ogni volta che viene visualizzato un codice a matrice di rilascio.
Dopo aver immesso il numero di PIN, viene visualizzata la schermata Aggiungi credenziali . Nella parte superiore della schermata viene visualizzato un messaggio Non verificato (in rosso). Questo avviso è correlato all'avviso di convalida del dominio indicato in precedenza.
Selezionare Aggiungi per accettare le nuove credenziali verificabili.

Complimenti. È ora disponibile una credenziale verificabile con un esperto di credenziali verificato.

Screenshot che mostra una credenziale verificabile appena aggiunta.

Tornare all'app di esempio. Mostra che una credenziale è stata emessa correttamente.

Screenshot che mostra una credenziale verificabile rilasciata correttamente.

Nomi di credenziali verificabili

Le credenziali verificabili contengono Megan Bowen per il nome e il cognome nella credenziale. Questi valori sono stati hardcoded nell'applicazione di esempio e sono stati aggiunti alle credenziali verificabili al momento del rilascio nel payload.

Negli scenari reali, l'applicazione esegue il pull dei dettagli utente da un provider di identità. Il frammento di codice seguente mostra dove è impostato il nome nell'applicazione di esempio.

//file: IssuerController.cs
[HttpGet("/api/issuer/issuance-request")]
public async Task<ActionResult> issuanceRequest()
  {
    ...
    // Here you could change the payload manifest and change the first name and last name.
    payload["claims"]["given_name"] = "Megan";
    payload["claims"]["family_name"] = "Bowen";
    ...
}

Passaggi successivi

Nel passaggio successivo si apprenderà come un'applicazione di terze parti, nota anche come applicazione relying party, può verificare le credenziali con il proprio servizio API per le credenziali verificabili del tenant Di Microsoft Entra.

Condividi tramite