Explicación de certificados y provisioning profiles de iOS

La firma de code en iOS utiliza dos componentes. Un certificado prueba quién creó la app, y un perfil de aprovisionamiento indica qué app es, qué dispositivos pueden ejecutarla y qué capacidades puede usar. Xcode rechazará el build para un dispositivo, y App Store Connect rechazará los uploads, a menos que el certificado, su clave privada y un perfil coincidente encajen todos.

Esta guía explica cada pieza, qué combinación necesitas para builds de desarrollo, ad hoc, TestFlight, App Store y enterprise, cómo crearlas con o sin un Mac, y cómo solucionar los errores que te encontrarás.

Por qué Apple exige el signing de code

Apple solo permite que los iPhones ejecuten code que Apple pueda rastrear hasta un desarrollador conocido. El signing le da a Apple tres garantías:

1. Identidad: el binario fue firmado por un miembro de un equipo concreto de Apple Developer.
2. Integridad: nadie modificó el binario después de firmarlo. Cambiar un solo byte rompe la firma.
3. Autorización: la app está permitida en este dispositivo, con estos entitlements (push, iCloud, Sign in with Apple, App Groups, etc.).

Los certificados aportan los dos primeros. Los provisioning profiles, el tercero.

Los componentes básicos

La confusión más común: un .cer archivo es inútil por sí solo. La firma requiere la clave privada que creó el CSR. Si pierdes esa clave, debes crear un nuevo certificado.

Tipos de certificados

Desarrollo de Apple

Se usa para ejecutar builds en tus propios dispositivos desde Xcode durante el desarrollo. Los certificados de desarrollo pertenecen a un desarrollador individual y Apple los etiqueta con el nombre del equipo. Cada desarrollador del equipo puede tener el suyo.

Distribución de Apple

Se usan para firmar builds para distribución Ad Hoc, TestFlight y la App Store. Los certificados de distribución pertenecen al equipo, y solo los roles Account Holder o Admin pueden crearlos. Apple limita cuántos puede tener un equipo, así que comparte uno a través de un almacén seguro en vez de que cada desarrollador cree el suyo.

Aún podrías ver Desarrollo para iOS y Distribución de iOS en cuentas antiguas. Son los tipos anteriores a Xcode 11. Apple Development y Apple Distribution los reemplazan y funcionan en iOS, iPadOS, macOS, tvOS, watchOS y visionOS.

Otros tipos de certificados que podrías encontrar

• Developer ID Application / Installer: para apps de Mac distribuidas fuera de la Mac App Store. No se usan para iOS.
• SSL de Apple Push Notification service: certificados de push heredados. Mejor usa un Clave de autenticación APNs (.p8), que no caduca anualmente y funciona para todas las apps del equipo. Consulta nuestra guía de certificados APNs.
• Identidad de comerciante de Apple Pay, ID de tipo de pase, ID de push para sitios web: servicios específicos.

Tipos de provisioning profile

Un perfil está vinculado a un App ID. Si tu app tiene extensiones (un widget, una extensión de servicio de notificaciones, una extensión de compartir), cada target tiene su propio bundle ID y necesita su propio perfil.

Cómo encajan las piezas

Cuando Xcode o un servicio de build firma tu app de Capacitor, comprueba:

1. El bundle ID de tu target (por ejemplo com.example.app) coincide con el App ID del perfil.
2. El certificado usado para firmar es uno de los certificados listados en el perfil.
3. La clave privada de ese certificado está disponible en el keychain.
4. Para builds de desarrollo y ad hoc, el UDID del dispositivo está en el profile.
5. El archivo de entitlements (push, associated domains, App Groups) es un subconjunto de lo que permiten el App ID y el profile.

Si falla alguna validación, obtendrás un error de signing, no un crash en runtime, lo cual es bueno: te enteras antes de hacer el deploy.

¿Qué combinación necesito?

TestFlight usa la misma mismo firma que la App Store. No hay un perfil de TestFlight aparte. Subes un build y decides en App Store Connect si va a testers, a revisión o a ambos.

Creación de certificados y perfiles

Opción 1: dejar que Xcode gestione la firma

Para el desarrollo local, esta es la opción más sencilla. Abre ios/App/App.xcworkspace (o el .xcodeproj cuando tu proyecto Capacitor 8 usa Swift Package Manager), selecciona el app target, abre Signing & Capabilities, marca Gestionar la firma automáticamente y elige tu equipo. Xcode crea el certificado de desarrollo, registra el dispositivo conectado y genera los perfiles por ti.

La firma automática se vuelve complicada en CI, porque la máquina de build necesita acceso a la cuenta del equipo y crea certificados por su cuenta. La mayoría de los equipos pasan a la firma manual, o a un servicio de build con firma basada en claves de API, para las builds de release.

Opción 2: crearlos manualmente en un Mac

1. Abrir Acceso a Llaveros > Asistente de Certificados > Solicitar un certificado a una autoridad de certificación. Introduce tu correo electrónico y elige Guardado en disco. Esto crea la clave privada en tu llavero y un .certSigningRequest archivo.
2. En el portal de Apple Developer, ve a Certificados, identificadores y perfiles > Certificados > +, elige Distribución de Apple (o Apple Development) y sube el CSR.
3. Descarga el .cer y haz doble clic en él. Keychain Access lo empareja con la clave privada.
4. Para exportar para CI: en Keychain Access, dentro de Mis certificados, haz clic derecho en el certificado y elige Exportar, guardar como .p12 con una contraseña segura.

Opción 3: crearlos sin un Mac

Puedes hacer todo el flujo con OpenSSL en Linux o Windows:

# 1. Private key and CSR
openssl genrsa -out ios_distribution.key 2048
openssl req -new -key ios_distribution.key -out ios_distribution.csr \
  -subj "/emailAddress=you@example.com/CN=Example Inc/C=US"

# 2. Upload ios_distribution.csr in the Apple Developer portal,
#    download the certificate as distribution.cer

# 3. Convert the .cer (DER) to PEM
openssl x509 -in distribution.cer -inform DER -out distribution.pem -outform PEM

# 4. Build the .p12 (signing identity)
openssl pkcs12 -export -inkey ios_distribution.key -in distribution.pem \
  -out ios_distribution.p12 -legacy

El -legacy el flag importa con OpenSSL 3: sin él, el .p12 usa algoritmos de cifrado que las herramientas de keychain de macOS rechazan con un error de “invalid password”, incluso cuando la contraseña es correcta.

Si prefieres no instalar OpenSSL, el generador de certificados iOS crea el CSR y la clave privada por ti. Vienen de un endpoint Capgo stateless que no los almacena, y solo su .cer a .p12 el conversor se ejecuta totalmente en tu navegador. Si tu política exige generar la clave en tu máquina, usa los comandos de OpenSSL de arriba.

Crear el perfil

1. Identifiers > +: registra un App ID con tu bundle ID exacto y habilita las capabilities que uses (Push Notifications, Sign in with Apple, Associated Domains…).
2. Devices > +: para perfiles de desarrollo y ad hoc, registra el UDID de cada tester. Los testers pueden obtenerlo en el propio teléfono con el Buscador de UDID de iOS, sin necesidad de Mac o cables.
3. Profiles > +: elige el tipo de perfil, el App ID, el/los certificado(s) y los dispositivos. Ponle un nombre claro, por ejemplo com.example.app AppStore 2026.
4. Descarga el .mobileprovision archivo.

Si agregas un dispositivo o una capacidad más adelante, debes regenerar y volver a descargar el perfil. Los perfiles existentes no se actualizan automáticamente.

Inspeccionar un perfil

Una .mobileprovision el archivo es un plist firmado. En macOS puedes leerlo así:

security cms -D -i App_Store.mobileprovision > profile.plist
/usr/libexec/PlistBuddy -c "Print :Name" profile.plist
/usr/libexec/PlistBuddy -c "Print :ExpirationDate" profile.plist
/usr/libexec/PlistBuddy -c "Print :Entitlements" profile.plist
/usr/libexec/PlistBuddy -c "Print :ProvisionedDevices" profile.plist

En Linux, openssl smime -inform der -verify -noverify -in App_Store.mobileprovision muestra el plist.

Para comprobar con qué se firmó un .ipa firmado con:

unzip -q App.ipa -d ipa
codesign -dvv ipa/Payload/App.app
codesign -d --entitlements :- ipa/Payload/App.app

Expiración y renovación

• Certificados son válidos durante un año desde su creación.
• Perfiles de aprovisionamiento expiran al año, o antes si el certificado que incluyen expira o se revoca.
• Las apps de la App Store siguen funcionando cuando el certificado de distribución caduca. Apple vuelve a firmar las descargas de la App Store. Solo necesitarás un nuevo certificado para subir nuevos builds.
• Los builds Ad Hoc y de desarrollo dejan de iniciarse cuando su perfil expira. Los testers ven que la app se cierra al iniciar.
• Builds de TestFlight expiran 90 días después de la subida, independientemente del certificado.
• Las apps Enterprise dejan de funcionar en cada dispositivo cuando el certificado de empresa caduca o se revoca. Renueva antes de la caducidad.
• Slots de dispositivos se restablece una vez por año de membresía. Eliminar un dispositivo no libera su cupo hasta que comience el siguiente año de membresía.

Anota la fecha de vencimiento del certificado en un calendario compartido. Nuestra guía de gestión de certificados explica a fondo el monitoreo y la rotación.

Errores comunes y soluciones

“No se encontró el certificado de firma ‘iOS Distribution’” o “El certificado de firma no es válido”: la clave privada no está en este keychain. Importa la .p12, o crea un nuevo certificado si nadie tiene la clave.

“El provisioning profile no incluye el certificado de firma”: el perfil se creó con un certificado distinto. Edita el perfil en el portal, selecciona el certificado actual, regenera y descarga.

“El provisioning profile no incluye el dispositivo seleccionado actualmente”: registra el UDID y regenera el perfil. No hace falta para TestFlight ni App Store.

“El provisioning profile no admite la capacidad de Push Notifications”: habilita la capability en el App ID y regenera el perfil. Los perfiles son snapshots.

“No se encontró un provisioning profile válido para este ejecutable” al instalar: el dispositivo no está en el perfil ad hoc o el perfil ha caducado.

La app se instala pero se cierra inmediatamente: en iOS 16 y posteriores, los builds de desarrollo y ad hoc requieren Developer Mode en el dispositivo. Ver cómo activar el Modo Desarrollador en iOS.

Error al firmar las extensiones: cada target de extensión necesita su propio App ID y perfil. Revisa cada target en Signing & Capabilities, no solo App.

“Invalid password” al importar un .p12 creado en Linux: vuelve a generarlo con openssl pkcs12 -export ... -legacy.

Upload rechazado para la versión SDK: desde abril de 2026 App Store Connect requiere builds con Xcode 26 y el SDK de iOS 26. Actualiza Xcode o tu imagen de CI. Capacitor 8 ya requiere Xcode 26.

Buenas prácticas para equipos

• Un certificado de Apple Distribution por equipo, guardado como un .p12 en un gestor de contraseñas o un secrets store, con la contraseña guardada por separado.
• Nunca por email .p12 archivos ni los hagas commit en git.
• Usa las keys de API de App Store Connect (.p8) para los uploads en lugar de contraseñas de Apple ID.
• Nombra los perfiles con el bundle ID, el tipo y el año.
• Revoca los certificados de quienes dejen el equipo.
• Mantén una lista escrita de cada bundle ID, extensión y capability que use la app.

Firma en la nube para apps Capacitor

No necesitas un Mac en el escritorio de cada desarrollador para lanzar builds de iOS. Build de Capgo genera builds de apps Capacitor en máquinas macOS de Capgo usando .p12 y el perfil que proporciones. Las credenciales solo se usan para el build y no se guardan en los servidores de Capgo. Guárdalas una vez desde CLI:

bunx @capgo/cli@latest build credentials save --appId com.example.app --platform ios
bunx @capgo/cli@latest build request com.example.app --platform ios --path .

El Docs de Capgo Build para iOS lista las opciones exactas de credenciales, incluyendo las claves de App Store Connect API para el upload a TestFlight y ad_hoc modo para builds de testers.

Una vez que tu primer build esté en TestFlight, puedes enviar cambios de JavaScript y assets a los usuarios con actualizaciones Live Update de Capgo sin tener que firmar un nuevo binario para cada fix. Los cambios nativos de code y nuevas capacidades aún requieren un build firmado a través de la store.

Próximos pasos

• ¿Necesitas cuentas primero? Cómo crear cuentas de desarrollador en Apple y Google Play.
• ¿Listo para pasar builds a los testers? Cómo distribuir apps de iOS y Android a testers.
• ¿Vas a enviar? Lee nuestro guía de envío de apps para iOS.