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

Artículo
01/17/2024

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.

Diagrama que muestra la arquitectura de Id. verificada por Microsoft Entra.

Requisitos previos

Configure un inquilino para Verified ID de Microsoft Entra.
Para clonar el repositorio que hospeda la aplicación de ejemplo, instale GIT.
Visual Studio Code, Visual Studio o editor de código similar.
.NET 7.0.
Descargue ngrok y regístrese para obtener una cuenta gratuita. Si en la organización no se puede usar ngrok por algún motivo, consulte estas preguntas frecuentes.
Un dispositivo móvil con la versión más reciente de Microsoft Authenticator.

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.

Inicie sesión en el centro de administración de Microsoft Entra como administrador global.
Seleccione Credenciales verificables.
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.

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

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.

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.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"
      }
    ]
}

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"
    ]
  }
}

Seleccione Crear.

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

Captura de pantalla que muestra cómo crear una credencial.

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.

En Credenciales verificables, seleccione Credenciales.
Copie el elemento authority, que es el identificador descentralizado y anótelo para usarlo en otro momento.
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.
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.

Inicie sesión en el centro de administración de Microsoft Entra como administrador global.
Seleccione Microsoft Entra ID.
Seleccione Aplicaciones>Registros de aplicaciones.
Seleccione la aplicación verifiable-credentials-app que creó anteriormente.
Seleccione el nombre que irá en los detalles de registro.
Copie el valor de Id. de aplicación (cliente) y guárdelo para usarlo más adelante.
En el menú principal, en Administrar, seleccione Certificados y secretos.
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.

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.
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.
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": "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"
  }
}

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.

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

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.
Abra la dirección URL HTTPS generada por ngrok.
En un explorador web, seleccione Get Credential (Obtener credencial).
Con el dispositivo móvil, digitalice el código QR con la aplicación Authenticator. Para más información sobre cómo leer el código QR, consulte la sección de preguntas frecuentes.
En este momento, verá un mensaje de advertencia que indica que esta aplicación o sitio web puede ser de riesgo. Seleccione Advanced (Avanzadas).
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]).
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.
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.
Seleccione Agregar para aceptar la nueva credencial verificable.

¡Enhorabuena! Ahora tiene una credencial verificable del experto en credenciales verificadas.

Captura de pantalla que muestra una credencial verificable recién agregada.

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

Captura de pantalla que muestra una credencial verificable emitida correctamente.

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.

Compartir vía