Explicación de certificados y provisioning profiles de iOS

La firma de iOS code usa dos elementos. Un certificado demuestra quién creó la app, y un perfil de aprovisionamiento indica qué app es, qué dispositivos pueden ejecutarla y qué capacidades puede usar. Xcode se niega a compilar para un dispositivo, y App Store Connect rechaza los uploads, a menos que el certificado, su clave privada y un perfil compatible estén todos alineados.

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

Por qué Apple exige el signing de code

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

1. Identidad: el binario lo firmó un miembro de un equipo específico 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 proporcionan los dos primeros. Los provisioning profiles, el tercero.

Los componentes básicos

La confusión más común: un .cer archivo no sirve de nada por sí solo. El signing 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 usa 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 de Account Holder o Admin pueden crearlos. Apple limita la cantidad que un equipo puede tener, así que comparte uno mediante un almacén seguro en lugar de dejar que cada desarrollador cree el suyo.

Es posible que aún veas 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 usa para iOS.
• SSL de Apple Push Notification service: certificados de push heredados. Es mejor usar 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 Apple Pay, ID de tipo Pass, ID de Push para 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 share extension), cada target tiene su propio bundle ID y necesita su propio perfil.

Cómo encajan todas las piezas

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

1. Que el bundle ID de tu target (por ejemplo, com.example.app) coincida con el App ID del perfil.
2. Que el certificado usado para la firma sea 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 firma que la App Store. No hay un perfil de TestFlight aparte. Subes un build y decides en App Store Connect si va a los testers, a revisión o a ambos.

Creación de certificados y perfiles

Opción 1: deja que Xcode gestione la firma

Para desarrollo local es lo más fácil. Abre ios/App/App.xcworkspace (o el .xcodeproj cuando tu proyecto Capacitor 8 usa Swift Package Manager), selecciona el App objetivo, abrir Signing y Capabilities, marca Gestiona el firmado automáticamente y elige tu equipo. Xcode crea el certificado de desarrollo, registra el dispositivo conectado y genera los profiles por ti.

El signing automático es un problema 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 manual signing, o a un servicio de build con API-key-based signing para los release builds.

Opción 2: créalos manualmente en un Mac

1. Abrir Acceso a Llaveros > Asistente de Certificados > Solicitar un certificado a una autoridad de certificación. Introduce tu email y elige Guardado en el disco. Esto crea la clave privada en tu keychain 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. Keychain Access lo vincula con la clave privada.
4. Para exportar para CI: en Keychain Access, bajo Mis certificados, haz clic derecho en el certificado y elige Export, guárdalo como .p12 con una contraseña segura.

Opción 3: crearlos sin un Mac

Puedes completar 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 flag es importante 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 si la contraseña es correcta.

Si prefieres no instalar OpenSSL, el generador de certificados iOS crea el CSR y la clave privada por ti. Provienen 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. Descargar el .mobileprovision archivo.

Si añades un dispositivo o una capability más tarde, deberás regenerar y descargar el perfil de nuevo. Los perfiles existentes no se actualizan solos.

Inspeccionar un perfil

Un .mobileprovision archivo es un plist firmado. En macOS puedes leerlo:

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 imprime el plist.

Para comprobar con qué se firmó un .ipa se firmó 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 por un año desde su creación.
• Perfiles de aprovisionamiento expiran al año, o antes si el certificado incluido caduca o es revocado.
• 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 de Ad Hoc y desarrollo dejan de abrirse cuando su perfil caduca. Los testers verán que la app se cierra al iniciar.
• Los builds de TestFlight expiran 90 días después de la subida, independientemente del certificado.
• Las apps Enterprise dejan de funcionar en todos los dispositivos cuando el certificado enterprise caduca o es revocado. Renuévalo antes de que expire.
• Slots de dispositivos se reinician una vez por año de membresía. Eliminar un dispositivo no libera su slot hasta que comience el siguiente año.

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

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, marca el certificado actual, regenéralo y descárgalo.

“El provisioning profile no incluye el dispositivo seleccionado actualmente”: registra el UDID y luego regenera el perfil. No es necesario para TestFlight o App Store.

“El provisioning profile no admite la capacidad de Push Notifications”: habilita la capability en el App ID y luego 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 expiró.

La app se instala y se cierra inmediatamente: en iOS 16 y versiones posteriores, los builds de development y ad hoc requieren Developer Mode en el dispositivo. Mira cómo habilitar Developer Mode en iOS.

Error al firmar las Extensions: cada target de la extension necesita su propio App ID y perfil. Revisa cada target en Signing & Capabilities, no solo la App.

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

Rechazo de upload 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 .p12 en un gestor de contraseñas o secrets store, con la clave guardada aparte.
• Never email .p12 archivos ni los hagas commit en git.
• Usa las keys de App Store Connect API (.p8) para los uploads en lugar de contraseñas de Apple ID.
• Nombra los profiles con el bundle ID, tipo y año.
• Revoca los certificados de quienes dejen el equipo.
• Mantén una lista de cada bundle ID, extension 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. Capgo Build genera builds de apps Capacitor en máquinas macOS de Capgo usando un .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 desde el 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 .

La doc de Capgo Build para iOS detalla las opciones de credenciales, incluyendo las claves API de App Store Connect 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 Live Updates 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 vía la store.

Siguientes pasos

• ¿Necesitas cuentas primero? Cómo crear cuentas de desarrollador en Apple y Google Play.
• ¿Listo para enviar builds a 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.