Emisión de credenciales de Id. verificada por Microsoft Entra desde una aplicación

En este tutorial, ejecutará una aplicación de ejemplo desde el equipo local que se conecta al inquilino de Microsoft Entra. Con la aplicación, va a emitir y a comprobar una tarjeta de experto en credenciales verificadas.

En este artículo aprenderá a:

  • Crear la tarjeta de experto en credenciales verificadas en Azure.
  • Recopilar las credenciales y los detalles del entorno para configurar la aplicación de ejemplo.
  • Descargar el código de la aplicación de ejemplo en el equipo local.
  • Actualizar la aplicación de ejemplo con la tarjeta de experto en credenciales verificadas y los detalles del entorno.
  • Ejecutar la aplicación de ejemplo y emitir su primera tarjeta de experto en credenciales verificadas.
  • Comprobar la tarjeta de experto en credenciales verificadas.

En el diagrama siguiente se muestra la arquitectura de Verified ID de Microsoft Entra y el componente que configure.

Diagram that illustrates the Microsoft Entra Verified ID architecture.

Requisitos previos

Creación de la tarjeta de experto en credenciales verificadas en Azure

Sugerencia

Los pasos de este artículo podrían variar ligeramente en función del portal desde donde comienza.

En este paso, creará la tarjeta de experto en credenciales verificadas mediante Verified ID de Microsoft Entra. Después de crear la credencial, el inquilino de Microsoft Entra puede emitirla a los usuarios que inician el proceso.

  1. Inicie sesión en el centro de administración de Microsoft Entra por lo menos como administrador global.

  2. Seleccione Credenciales verificables.

  3. Después de configurar el inquilino, debería aparecer Crear credencial. Como alternativa, puede seleccionar Credenciales en el menú de la izquierda y seleccionar + Agregar una credencial.

  4. En Crear credencial, seleccione el elemento Credencial personalizada y haga clic en Siguiente. Después, siga estos pasos:

    1. En Nombre de credencial, escriba VerifiedCredentialExpert. Este nombre su usa en el portal para identificar las credenciales verificables. Se incluye como parte del contrato de credenciales verificables.

    2. Copie el siguiente JSON y péguelo en el cuadro de texto Definición de visualización

      {
          "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"
            }
          ]
      }
      
    3. Copie el siguiente JSON y péguelo en el cuadro de texto Definición de reglas

      {
        "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"
          ]
        }
      }
      
    4. Seleccione Crear.

En la captura de pantalla siguiente, se muestra cómo crear una credencial:

Screenshot that shows how to create a new credential.

Recopilación de credenciales y detalles del entorno

Ahora que tiene una nueva credencial, va a recopilar información sobre su entorno y la credencial que ha creado. Estos fragmentos de información los usará al configurar la aplicación de ejemplo.

  1. En Credenciales verificables, seleccione Credenciales.

    Screenshot that shows how to select the newly created verified credential.

  2. Copie el elemento authority, que es el identificador descentralizado y anótelo para usarlo en otro momento.

  3. Copie la dirección URL de manifest. Es la dirección URL que Authenticator evalúa antes de mostrar los requisitos de emisión de las credenciales verificables al usuario. Anótela para usarla en otro momento.

  4. Copie el identificador de inquilino y anótelo para usarlo en otro momento. El id. de inquilino es el guid en la dirección URL del manifiesto resaltada en rojo arriba.

Descarga del código de ejemplo

La aplicación de ejemplo está disponible en .NET y el código se mantiene en un repositorio de GitHub. Descargue el código de ejemplo de Github, o bien, clone el repositorio en la máquina local:

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

Configuración de la aplicación de credenciales verificables

Cree un secreto de cliente para la aplicación registrada que ha creado. La aplicación de ejemplo usa el secreto de cliente para demostrar su identidad al solicitar tokens.

  1. Inicie sesión en el centro de administración de Microsoft Entra por lo menos como administrador global.

  2. Seleccione Microsoft Entra ID.

  3. Seleccione Aplicaciones>Registros de aplicaciones.

  4. Seleccione la aplicación verifiable-credentials-app que creó anteriormente.

  5. Seleccione el nombre que irá en los detalles de registro.

  6. Copie el valor de Id. de aplicación (cliente) y guárdelo para usarlo más adelante.

    Screenshot that shows how to copy the app registration ID.

  7. En el menú principal, en Administrar, seleccione Certificados y secretos.

  8. Seleccione Nuevo secreto de cliente y haga lo siguiente:

    1. En Descripción, escriba una descripción para el secreto de cliente (por ejemplo, vc-sample-secret).

    2. En Expira, seleccione el tiempo durante el cual es válido el secreto (por ejemplo, 6 meses). A continuación, seleccione Agregar.

    3. Registre el Valor del secreto. Este valor se usará para la configuración en un paso posterior. El valor del secreto no se volverá a mostrar y no se podrá recuperar por ningún otro medio. Regístrelo en cuanto esté visible.

En este momento, debe tener toda la información necesaria para configurar la aplicación de ejemplo.

Actualización de la aplicación de ejemplo

Ahora, realizará modificaciones en el código del emisor de la aplicación de ejemplo para actualizarlo con la dirección URL de la credencial verificable. Este paso le permite emitir credenciales verificables mediante su propio inquilino.

  1. En la carpeta active-directory-verifiable-credentials-dotnet-main, abra Visual Studio Code y seleccione el proyecto dentro de la carpeta 1.asp-net-core-api-idtokenhint.

  2. En la carpeta raíz del proyecto, abra el archivo appsettings.json. Este archivo contiene información sobre el entorno de Verified ID de Microsoft Entra. Actualice las siguientes propiedades con la información que registró en los pasos anteriores:

    1. Id. de inquilino: su identificador de inquilino
    2. Id. de cliente: su identificador de cliente
    3. Secreto de cliente: su secreto de cliente
    4. DidAuthority: su identificador descentralizado
    5. CredentialManifest: la dirección URL del manifiesto

    CredentialType solo es necesario para la presentación, por lo que si todo lo que desea hacer es la emisión, no es necesario estrictamente.

  3. Guarde el archivo appSettings.json.

El siguiente JSON muestra un archivo appsettings.json completo:

{
  "VerifiedID": {
    "Endpoint": "https://verifiedid.did.msidentity.com/v1.0/verifiableCredentials/",
    "VCServiceScope": "3db474b9-6a0c-4840-96ac-1fceb342124f/.default",
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "12345678-0000-0000-0000-000000000000",
    "ClientId": "33333333-0000-0000-0000-000000000000",
    "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/12345678-0000-0000-0000-000000000000/verifiableCredentials/contracts/VerifiedCredentialExpert"
  }
}

Emisión de la primera tarjeta de experto en credenciales verificadas

Ahora está listo para emitir su primera tarjeta de experto en credenciales verificadas mediante la ejecución de la aplicación de ejemplo.

  1. En Visual Studio Code, ejecute el proyecto Verifiable_credentials_DotNet. O bien, desde la línea de comandos del sistema operativo, ejecute:

    cd active-directory-verifiable-credentials-dotnet\1-asp-net-core-api-idtokenhint
    dotnet build "AspNetCoreVerifiableCredentials.csproj" -c Debug -o .\bin\Debug\net6.
    dotnet run
    
  2. En otra ventana del símbolo del sistema, ejecute el comando siguiente. Este comando ejecuta ngrok para configurar una dirección URL en 5000 y hacer que esté disponible públicamente en Internet.

    ngrok http 5000
    

    Nota:

    En algunos equipos, podría tener que ejecutar el comando en este formato: ./ngrok http 5000.

  3. Abra la dirección URL HTTPS generada por ngrok.

    Screenshot that shows how to get the ngrok public URL.

  4. En un explorador web, seleccione Get Credential (Obtener credencial).

    Screenshot that shows how to choose to get the credential from the sample app.

  5. Con el dispositivo móvil, digitalice el código QR con la aplicación Authenticator. También puede digitalizar el código QR directamente desde la cámara, que abrirá la aplicación Authenticator automáticamente.

    Screenshot that shows how to scan the QR code.

  6. En este momento, verá un mensaje de advertencia que indica que esta aplicación o sitio web puede ser de riesgo. Seleccione Advanced (Avanzadas).

    Screenshot that shows how to respond to the warning message.

  7. En la advertencia de sitio web de riesgo, seleccione Proceed anyways (unsafe) (Continuar de todos modos [no seguro]). Aparece esta advertencia porque el dominio no está vinculado al identificador descentralizado (DID). Para comprobar el dominio, siga Vinculación del dominio a su identificador descentralizado (DID). En este tutorial, puede omitir el registro de dominio y seleccionar Proceed anyways (unsafe) (Continuar de todos modos [no seguro]).

    Screenshot that shows how to proceed with the risky warning.

  8. Se le pedirá que escriba un código PIN que se muestra en la pantalla donde ha digitalizado el código QR. El PIN agrega una capa adicional de protección a la emisión. Este código se genera aleatoriamente cada vez que se muestra un código QR de emisión.

    Screenshot that shows how to type the pin code.

  9. Después de escribir el número PIN, aparece la pantalla Agregar una credencial. En la parte superior de la pantalla, puede ver el mensaje Sin comprobar (en color rojo). Esta advertencia está relacionada con la validación de dominio mencionada anteriormente.

  10. Seleccione Agregar para aceptar la nueva credencial verificable.

    Screenshot that shows how to add your new credential.

Felicidades. Ahora tiene una credencial verificable del experto en credenciales verificadas.

Screenshot that shows a newly added verifiable credential.

Vuelva a la aplicación de ejemplo. Muestra que una credencial se emitió correctamente.

Screenshot that shows a successfully issued verifiable credential.

Nombres de credenciales verificables

La credencial verificable contiene Megan Bowen, correspondiente a los valores de nombre y apellido de la credencial. Estos valores se codificaron de forma rígida en la aplicación de ejemplo y se agregaron a la credencial verificable en el momento de la emisión de la carga.

En escenarios reales, la aplicación extrae los detalles del usuario de un proveedor de identidades. El siguiente fragmento de código muestra dónde se establece el nombre en la aplicación de ejemplo.

//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";
    ...
}

Pasos siguientes

En el paso siguiente descubrirá cómo la aplicación de terceros, también conocida como aplicación de usuario de confianza, puede comprobar sus credenciales con su propio servicio de API de credenciales verificables del inquilino de Microsoft Entra.