iOS Certificados y Perfiles de Provisión Explained

iOS code de firma utiliza dos piezas. Una certificado prueba quién construyó la aplicación, y un perfil de provisión dice qué aplicación es, qué dispositivos pueden ejecutarla y qué capacidades puede utilizar. Xcode se niega a construir para un dispositivo, y App Store Connect se niega a subir archivos, a menos que el certificado, su clave privada y un perfil coincidente se alineen.

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

¿Por qué Apple requiere code de firma

Apple solo permite que los iPhones ejecuten code que Apple pueda rastrear hasta un desarrollador conocido.

1. Identidad: la binaria fue firmada por un miembro de un equipo de desarrolladores de Apple específico.
2. Integridad: nadie modificó la binaria después de la firma. Cambiar un byte rompe la firma.
3. Autorización: la aplicación está permitida en este dispositivo, con estas autorizaciones (push, iCloud, Iniciar sesión con Apple, grupos de aplicaciones, etc.).

Los certificados proporcionan los dos primeros. Los perfiles de configuración proporcionan el tercero.

Los bloques de construcción

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

Tipos de certificados

Desarrollo de Apple

Usado para ejecutar compilaciones en dispositivos propios desde Xcode durante el desarrollo. Los certificados de desarrollo pertenecen a un desarrollador individual, y Apple los etiqueta con el nombre del ordenador. Cada desarrollador del equipo puede tener el suyo propio.

Distribución de Apple

Usado para firmar compilaciones para la distribución Ad Hoc, TestFlight y la Tienda de Aplicaciones. Los certificados de distribución pertenecen al equipo, y solo el titular de la cuenta o el rol de administrador pueden crearlos. Apple limita la cantidad que un equipo puede tener, por lo que comparte uno a través de un almacén seguro en lugar de dejar que cada desarrollador cree el suyo propio.

Puede ver aún Desarrollo de iOS y Distribución iOS en cuentas más antiguas. Son los tipos pre-Xcode 11. Apple Development y Apple Distribution los reemplazan y funcionan en iOS, iPadOS, macOS, tvOS, watchOS y visionOS.

Otros tipos de certificados que puede encontrar

• ID de Desarrollador de Aplicación / Instalador: para aplicaciones de Mac distribuidas fuera de la Mac App Store. No se utiliza para iOS.
• Servicio SSL de Notificación de Apple Push: certificados de notificación legados. Prefiera un Clave de Autenticación de APNs (.p8) que no expira anualmente y funciona para cada aplicación del equipo. Consulte nuestra Guía de certificados de APNs.
• Identidad de Comerciante de Apple Pay, ID de tipo de pase, ID de empuje de sitio web: servicios específicos.

Tipos de perfiles de configuración

Un perfil está ligado a una ID de AppSi su aplicación tiene extensiones (un widget, una extensión de servicio de notificaciones, una extensión de compartir), cada destino tiene su propio ID de paquete y necesita su propio perfil.

Cómo se ajustan las piezas

Cuando Xcode o un servicio de compilación firma su Capacitor aplicación, verifica:

1. El ID de paquete en su destino (por ejemplo com.example.app) coincide con la ID de App en el perfil.
2. El certificado utilizado para firmar es uno de los certificados listados en el perfil.
3. La clave privada para ese certificado está disponible en la llave de cadena.
4. Para compilaciones de desarrollo y ad hoc, el UDID del dispositivo está en el perfil.
5. El archivo de permisos (envío, dominios asociados, grupos de aplicaciones) es un subconjunto de lo que permiten la ID de App y el perfil.

Si falla algún cheque, obtendrás un error de firma, no un error de ejecución, lo cual es bueno: descubrirás el problema antes de enviar.

¿Cuál combinación necesito?

TestFlight utiliza el mismo mismo firmado como la Tienda de Aplicaciones. No existe un perfil separado de TestFlight. Carga una sola versión y decide en App Store Connect si se envía a los testers, a revisión o ambos.

Crear certificados y perfiles

Opción 1: dejar que Xcode gestione la firma

Para el desarrollo local esto es lo más fácil. Abre ios/App/App.xcworkspace (o el .xcodeproj cuando tu proyecto de Capacitor 8 utiliza el Gestor de Paquetes de Swift), selecciona el App target, abre Configuración y capacidades de firma, marca Administra automáticamente la firma y elige tu equipo. Xcode crea el certificado de desarrollo, registra el dispositivo conectado y genera perfiles para ti.

La firma automática se vuelve dolorosa en CI, porque la máquina de compilación necesita acceso a la cuenta del equipo y crea certificados por su cuenta. La mayoría de los equipos cambian a la firma manual, o a un servicio de compilación con firma basada en clave API, para las compilaciones de lanzamiento.

Opción 2: crea ellos manualmente en un Mac

1. Abre Acceso a la llave > Asistente de certificado > Solicita un certificado de una autoridad de certificado. Ingresa tu correo electrónico, elige Guardado en disco. Esto crea la clave privada en tu llave de acceso y un .certSigningRequest archivo.
2. En el portal del desarrollador de Apple ve a Certificados, identificadores y perfiles > Certificados > +escolha Distribución de Apple (o desarrollo de Apple) y subir el CSR.
3. Descargar el .cer y hazle doble clic. Acceso a la llave de cadena lo asocia con la clave privada.
4. Para exportar para CI: en Keychain Access, en la sección Mis certificados, haz clic derecho en el certificado, seleccione Exportar, guardar como .p12 con una contraseña fuerte.

Opción 3: crearlos sin un Mac

Puedes realizar 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 importa con OpenSSL 3: sin él, el .p12 usa algoritmos de cifrado que las herramientas de llave de macOS rechazan con un error de ‘contraseña inválida’ incluso cuando la contraseña es correcta.

Si prefieres no instalar OpenSSL, el generador de certificados de iOS crea el CSR y la clave privada para ti. Proceden de un endpoint estatal Capgo que no los almacena, y solo su .cer to .p12 El conversor se ejecuta completamente en tu navegador. Si tu política requiere que la clave se genere en tu máquina, utiliza los comandos OpenSSL anteriores.

Identificadores > +

1. Identificadores > +Registre un ID de App con tu ID de paquete exacto y habilita las capacidades que utilices (Notificaciones de Push, Iniciar sesión con Apple, Dominios asociados…).
2. Dispositivos > +Para los perfiles de desarrollo y ad hoc, registre cada UDID del tester. Los testers pueden obtenerlo en el propio teléfono con el. iOS buscador de UDID, sin necesidad de Mac ni cable.
3. Perfiles > +: elija el tipo de perfil, el ID de la aplicación, los certificados(s) y los dispositivos. Nómbralo claramente, por ejemplo com.example.app AppStore 2026.
4. Descargar el .mobileprovision archivo.

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

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 verificar qué una construcción .ipa fue firmada con:

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

Vencimiento y renovación

• Certificados son válidos durante un año desde su creación.
• Perfiles de distribución expiran después de un año, o antes si el certificado que incluyen vence o se revoca.
• Las aplicaciones de App Store siguen funcionando después de que vence el certificado de distribución. Apple re-firma las descargas de App Store. Solo necesitas un nuevo certificado para subir nuevas construcciones.
• Los builds Ad Hoc y de desarrollo dejan de lanzarse Una vez que expira su perfil, los probadores ven que la aplicación se cae al iniciar.
• Construcciones de TestFlight Vencen 90 días después de subirlos, independientes del certificado.
• Las aplicaciones de empresa dejan de funcionar en todos los dispositivos cuando el certificado de empresa expira o se revoca. Renueva antes de que expire.
• Ocupaciones de dispositivo reiniciar una vez por año de membresía. Eliminar un dispositivo no libera su ranura hasta que comience el próximo año de membresía.

Coloque la fecha de vencimiento del certificado en un calendario compartido. Nuestro guía de gestión de certificados aborda la supervisión y la rotación en mayor profundidad.

Errores y soluciones comunes

“No se encontró el certificado de firma ‘iOS Distribution’” o “El certificado de firma es inválido”El archivo privado no se encuentra en esta cadena de claves. Importe el .p12o cree un nuevo certificado si nadie tiene la clave.

“El perfil de provisión no incluye el certificado de firma”La perfil fue creado con un certificado diferente. Edite el perfil en el portal, marque el certificado actual, regenere y descargue.

“El perfil de provisión no incluye el dispositivo seleccionado actualmente”Registre el UDID, luego regenera el perfil. No es necesario para TestFlight o App Store.

“El perfil de provisión no admite la capacidad de notificaciones de empuje”Habilite la capacidad en el ID de la aplicación, luego regenere el perfil. Los perfiles son instantáneas.

“No se encontró un perfil de provisión válido para este ejecutable” en la instalación: el dispositivo no está en el perfil ad hoc, o el perfil expiró.

Instala la aplicación, luego se cierra inmediatamente: en iOS 16 y posteriores, los builds de desarrollo y ad hoc requieren el modo de desarrollador en el dispositivo. Consulte ¿Cómo habilitar el modo de desarrollador en iOS.

Las extensiones no pueden firmarCada objetivo de extensión necesita su propio ID de App y perfil. Verifique todos los objetivos en Signing & Capabilities, no solo la App.

“Contraseña inválida” al importar un .p12 creado en Linux: reconstrúyalo con openssl pkcs12 -export ... -legacy.

La subida rechazada para la versión SDK: desde abril de 2026, App Store Connect requiere builds realizados con Xcode 26 y el iOS 26 SDK. Actualice Xcode o su imagen de CI. Capacitor 8 ya requiere Xcode 26.

Prácticas recomendadas para equipos

• Una sola certificación de distribución de Apple por equipo, almacenada como un .p12 en un administrador de contraseñas o almacén de secretos, con la contraseña almacenada por separado.
• Never envíe .p12 archivos o los cometa en Git.
• Utilice las claves de App Store Connect API (.p8) para subir archivos en lugar de contraseñas de Apple ID.
• Nombra los perfiles con ID de paquete, tipo y año.
• Revóque las certificaciones de las personas que dejen el equipo.
• Mantenga una lista escrita de cada ID de paquete, extensión y capacidad que utiliza la aplicación.

La firma en la nube para Capacitor aplicaciones

No necesita un Mac en cada escritorio de desarrollador para enviar compilaciones de iOS. Capgo Construcción construye aplicaciones Capacitor en máquinas macOS de Capgo utilizando un .p12 y el perfil que proporcionas. Los credenciales se utilizan solo para la compilación y no se almacenan en los servidores Capgo. Guardalas una vez 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 .

El Capgo Documentación de construcción de iOS listar las opciones de credenciales exactas, incluyendo las claves de App Store Connect API para subir a TestFlight ad_hoc modo para compilaciones de pruebas.

Una vez que su primera construcción esté en TestFlight, puede enviar cambios de JavaScript y recursos a los usuarios con Capgo actualizaciones en vivo sin volver a firmar una nueva binaria para cada corrección. Los cambios nativos code y nuevas capacidades siguen requiriendo una construcción firmada a través de la tienda.

Pasos siguientes

• ¿Necesita cuentas primero? Cómo crear cuentas de desarrollador de Apple y Google Play.
• ¿Preparado para entregar builds a los probadores? ¿Listo para entregar construcciones a los probadores?.
• ¿Solicitando? Lea nuestra Guía de presentación de aplicaciones iOS.