Tu FIEL en tu propio Azure Key Vault

Una suscripción de Azure es simplemente tu cuenta de facturación: el contenedor donde vivirán los recursos que crees. Si tu empresa ya tiene una, pídele acceso a tu área de sistemas y salta al paso 2.

1. Entra a azure.microsoft.com/free y haz clic en Comenzar gratis.
2. Inicia sesión con una cuenta Microsoft. Si vas a usarlo para la empresa, crea una cuenta con el correo corporativo en lugar de usar una personal.
3. Llena tus datos y verifica con teléfono y tarjeta. Azure hace un cargo temporal de verificación (se reembolsa); no se te cobra nada por usar la cuenta gratuita.
4. Al terminar llegarás al portal en portal.azure.com. Ya tienes suscripción.

El Key Vault es la caja fuerte donde guardarás tu llave. Azure la administra por ti; tú solo decides quién entra.

1. En el portal, escribe Key vaults en la barra de búsqueda superior y entra a la sección que aparece bajo Services (servicios).

2. Ya dentro de Key vaults, haz clic en + Create.
3. Llena la pestaña Basics (datos básicos) con estos valores:

4. Ve a la pestaña Access configuration y en Permission model elige Azure role-based access control (RBAC). Este paso importa: el paso 6 asume RBAC.
5. Haz clic en Review + create y luego en Create. Espera a que termine el despliegue (menos de un minuto).
6. Abre el vault recién creado y copia su Vault URI desde la pantalla de Overview (la verás completa en el paso 3). Se ve así:

https://kv-miempresa-fiel.vault.azure.net/

Tu tenant (o directorio) es la organización dueña de la cuenta. Su ID es un identificador largo que le dice a SatGo a qué directorio pedirle permiso.

No hace falta ir a buscarlo a otra pantalla: los dos datos que necesitas están en el Overview de tu propio Key Vault, en el panel Essentials.

1. Abre tu Key Vault y quédate en Overview (es la pantalla que abre por omisión).
2. En la columna derecha del panel Essentials copia Vault URI (el del paso 2) y Directory ID.

3f2a91c4-7b8d-4e15-9a06-2c5d8e7f1b3a

Para que tu vault pueda darle permiso a SatGo, primero necesitas saber quién es SatGo dentro de Azure. Ese dato lo entrega el endpoint GET /api/v1/secretprovider/identity, que además te devuelve la guía completa en formato JSON.

curl -X GET "https://api.sat-go.com/api/v1/secretprovider/identity" \
  -H "Authorization: Bearer <TU_TOKEN_JWT>"

{
  "crossTenant": {
    "consent": {
      "appClientId": "8c1d5e90-4f3b-42a7-b6e8-0d9c7a1f2e34",
      "adminConsentUrl": "https://login.microsoftonline.com/YOUR_TENANT_ID/adminconsent?client_id=8c1d5e90-4f3b-42a7-b6e8-0d9c7a1f2e34",
      "steps": [ "..." ]
    },
    "signingKey_fiel": {
      "endpoint": "POST /api/v1/secretprovider/signing-key/register",
      "requiredKvRole": "Key Vault Crypto User",
      "example": {
        "rfc": "XAXX010101ABC",
        "providerType": "AzureKeyVault",
        "providerUri": "https://mi-vault.vault.azure.net/",
        "keyName": "fiel-xaxx010101abc",
        "keyOptions": { "tenantId": "<tu-tenant-id>" }
      }
    }
  },
  "satGoManaged": { "...": "la alternativa sin Azure" }
}

Este paso crea una Aplicación empresarial de SatGo dentro de tu tenant. Piénsalo como darle de alta un gafete de visitante: existe en tu edificio, pero todavía no abre ninguna puerta. Los permisos reales se los das en el paso 6.

1. Toma el adminConsentUrl del paso 4 y reemplaza YOUR_TENANT_ID por tu Tenant ID del paso 3:

https://login.microsoftonline.com/3f2a91c4-7b8d-4e15-9a06-2c5d8e7f1b3a/adminconsent?client_id=8c1d5e90-4f3b-42a7-b6e8-0d9c7a1f2e34

2. Ábrela en el navegador e inicia sesión con una cuenta administrador global de tu tenant.
3. Lee la pantalla de consentimiento y acepta. Azure te redirigirá a una página que puede mostrar un error de navegación: es normal e inofensivo, el consentimiento ya quedó registrado.
4. Verifícalo en Microsoft Entra ID → Enterprise applications: debe aparecer una app cuyo Application ID coincide con el appClientId.

Ahora sí, la parte que define qué puede hacer SatGo. Le asignarás el rol Key Vault Crypto User, que permite usar la llave para firmar pero no exportarla ni leerla. Es exactamente el permiso mínimo que necesita.

1. Abre tu Key Vault en el portal.
2. En el menú izquierdo entra a Access control (IAM) y haz clic en + Add → Add role assignment.
3. En la pestaña Role, busca y selecciona Key Vault Crypto User. Next.
4. En Members, deja User, group, or service principal y haz clic en + Select members. Busca satgo-kv-byos-reader: es el nombre de la aplicación de SatGo que creó el consentimiento del paso 5. También puedes buscarla pegando el appClientId del paso 4.
5. Review + assign. El permiso puede tardar hasta 5 minutos en propagarse.

az role assignment create \
  --role "Key Vault Crypto User" \
  --assignee 8c1d5e90-4f3b-42a7-b6e8-0d9c7a1f2e34 \
  --scope "/subscriptions/<TU_SUBSCRIPTION_ID>/resourceGroups/rg-satgo/providers/Microsoft.KeyVault/vaults/kv-miempresa-fiel"

El SAT te entrega la FIEL en dos archivos separados (.cer y .key), pero Azure los quiere juntos en un solo archivo PKCS#12 (.pfx). Vamos a convertirlos con OpenSSL y luego importarlos.

7.1 — Convertir los archivos del SAT a .pfx

Tienes dos caminos. El primero es una herramienta que hicimos justo para esto; el segundo es OpenSSL, por si prefieres no descargar nada.

Opción A — Convertidor de SatGo (recomendado)

Descarga convertidorpkcs12.zip (81 KB) y descomprímelo. Hace la conversión en un solo comando, sin archivos intermedios con tu llave expuesta. Requiere tener instalado el runtime de .NET 10.

SatScraper.Pkcs12Tool <certificado.cer> <llave.key> <password> [directorioSalida] [nombre.pfx]

SatScraper.Pkcs12Tool fiel.cer fiel.key "MiContraseñaFIEL" ./salida XAXX010101ABC.pfx

# → PKCS12 generado exitosamente en: ./salida\XAXX010101ABC.pfx

Opción B — OpenSSL

Los archivos del SAT vienen en formato DER, por eso los pasos intermedios. Necesitas OpenSSL instalado (en Windows viene incluido con Git Bash).

# 1. El .key del SAT (DER cifrado) → PEM. Te pedirá la contraseña de tu FIEL.
openssl pkcs8 -inform DER -in fiel.key -out fiel_privada.pem

# 2. El .cer del SAT (DER) → PEM
openssl x509 -inform DER -in fiel.cer -out fiel_cert.pem

# 3. Unir ambos en un PKCS#12. Define aquí una contraseña para el .pfx.
openssl pkcs12 -export \
  -inkey fiel_privada.pem \
  -in fiel_cert.pem \
  -out fiel.pfx

7.2 — Importar el .pfx como llave en el Key Vault

Fíjate bien en esto: la FIEL se importa en la sección Keys, no en Certificates. SatGo firma usando una llave (/keys/<nombre>) y el rol que le diste en el paso 6, Key Vault Crypto User, es justamente de llaves.

1. En el menú izquierdo de tu vault abre Objects → Keys y haz clic en + Generate/Import.

2. En Options elige Import.
3. En File Upload selecciona el .pfx que generaste en el paso 7.1.
4. Al seleccionarlo aparece un campo Password. Escribe ahí la contraseña de tu FIEL: es la misma que le pasaste al convertidor en el paso 7.1, porque el .pfx quedó protegido con ella.
5. En Name escribe el nombre de la llave. Este es el valor exacto que irá en keyName en el paso 8, así que anótalo.
6. Deja Key type en RSA y Enabled en Yes. Los demás campos (fechas de activación y expiración, opciones confidenciales) déjalos como vienen.
7. Create.

Este es el paso final de configuración: le dices a SatGo dónde está tu llave. Fíjate que no envías la llave, solo la dirección donde vive.

curl -X POST "https://api.sat-go.com/api/v1/secretprovider/signing-key/register" \
  -H "Authorization: Bearer <TU_TOKEN_JWT>" \
  -H "Content-Type: application/json" \
  -d '{
    "rfc": "XAXX010101ABC",
    "providerType": "AzureKeyVault",
    "providerUri": "https://kv-miempresa-fiel.vault.azure.net/",
    "keyName": "fiel-xaxx010101abc",
    "keyOptions": "{\"tenantId\": \"3f2a91c4-7b8d-4e15-9a06-2c5d8e7f1b3a\"}"
  }'

{
  "rfc": "XAXX010101ABC",
  "providerType": "AzureKeyVault",
  "providerUri": "https://kv-miempresa-fiel.vault.azure.net/",
  "keyName": "fiel-xaxx010101abc",
  "message": "Proveedor de firma registrado. Envía solo el .cer en las peticiones para usar firma remota."
}

Primero confirma el estado del registro:

curl -X GET "https://api.sat-go.com/api/v1/secretprovider/signing-key/XAXX010101ABC/status" \
  -H "Authorization: Bearer <TU_TOKEN_JWT>"

{
  "rfc": "XAXX010101ABC",
  "isRegistered": true,
  "providerType": "AzureKeyVault",
  "providerUri": "https://kv-miempresa-fiel.vault.azure.net/",
  "keyName": "fiel-xaxx010101abc",
  "updatedAt": "2026-07-16T10:32:00Z"
}

Y ahora la prueba de fuego: descarga tu Constancia de Situación Fiscal mandando solo el .cer. Sin llavePrivada, sin Contrasena.

curl -X POST "https://api.sat-go.com/api/v2/consultar/csffiel" \
  -H "Authorization: Bearer <TU_TOKEN_JWT>" \
  -F "Rfc=XAXX010101ABC" \
  -F "Certificado=@fiel.cer" \
  --output constancia.pdf