React Native Code Signing: Zertifikate und Provisioning Profiles

1. Warum Code Signing für React Native Apps unverzichtbar ist

Code Signing ist der Mechanismus, mit dem iOS und Android kryptografisch prüfen, dass eine App tatsächlich von der angegebenen Entwickler-Identität stammt und seit der Signierung nicht verändert wurde. Für React Native Apps ändert sich an diesem Prinzip nichts gegenüber rein nativen Apps - der JavaScript-Bundle wird zwar in Metro gebaut, aber am Ende entsteht ein natives iOS- oder Android-Paket, das exakt denselben Signing-Regeln unterliegt wie eine in Swift oder Kotlin geschriebene App. Wer Code Signing als lästige Nebensache behandelt, stolpert spätestens beim ersten TestFlight-Upload oder bei der ersten Play-Store-Einreichung über kryptische Fehlermeldungen.

Der Unterschied zwischen iOS und Android ist dabei fundamental. Apple verlangt ein zentral verwaltetes System aus Zertifikaten, App IDs und Provisioning Profiles, das über den Apple Developer Account gesteuert wird. Android dagegen basiert auf einem selbst erzeugten Keystore, den der Entwickler eigenverantwortlich sichert. Beide Systeme verfolgen dasselbe Ziel: sicherzustellen, dass Updates einer App nur von derselben Identität stammen können wie die Erstinstallation. Die folgenden Abschnitte erklären beide Systeme im Detail und zeigen, wie Werkzeuge wie EAS und Fastlane das manuelle Code Signing heute weitgehend automatisieren.

2. Das Apple-Zertifikatssystem: Certificates, CSR und Team ID

Im Zentrum des iOS-Code Signing steht das Zertifikat. Es wird über eine Certificate Signing Request (CSR) angefordert, die auf einem privaten Schlüssel basiert, der lokal im Schlüsselbund (macOS) oder verschlüsselt in einem Credentials-Store (EAS) erzeugt wird. Apple signiert diese CSR und stellt ein öffentliches Zertifikat aus, das an den privaten Schlüssel gebunden ist. Für die Entwicklung gibt es Development-Zertifikate, für die Veröffentlichung Distribution-Zertifikate - beide Typen sind an eine Team ID gebunden, die den Apple Developer Account eindeutig identifiziert.

Ein häufiges Missverständnis: Das Zertifikat allein reicht nicht aus, um eine App auf einem Gerät zu installieren oder im App Store einzureichen. Es ist nur die halbe Miete des Code Signing-Prozesses - die andere Hälfte ist das Provisioning Profile, das im nächsten Abschnitt erklärt wird. Wichtig ist außerdem: Verliert man den privaten Schlüssel eines Zertifikats, etwa durch einen Rechnerwechsel ohne Schlüsselbund-Export, muss ein komplett neues Zertifikat erstellt und in allen betroffenen Provisioning Profiles neu verknüpft werden.

# Generate a Certificate Signing Request locally (manual workflow)
# 1. Open Keychain Access -> Certificate Assistant -> Request a Certificate
# 2. Save the .certSigningRequest file, upload it in the Apple Developer portal
# 3. Download the resulting .cer file and double-click to install it

# Equivalent, fully automated via EAS credentials manager
eas credentials
# Select platform: iOS
# Select: Build Credentials -> Set up a new Distribution Certificate
# EAS generates the CSR, uploads it to Apple, stores the private key encrypted

3. Provisioning Profiles: App ID, Geräte und Zertifikat verbinden

Ein Provisioning Profile ist die Datei, die drei Elemente zu einer gültigen Signing-Konfiguration verbindet: die App ID (den Bundle Identifier der App), ein oder mehrere Zertifikate und - bei Development- und Ad-Hoc-Profilen - eine Liste registrierter Testgeräte über deren UDID. Ohne ein passendes Provisioning Profile verweigert iOS die Installation einer App, selbst wenn das Zertifikat gültig ist. Für Code Signing in Produktionsumgebungen gibt es drei relevante Profil-Typen: App Store Profile für die Veröffentlichung, Ad Hoc Profile für Tests auf registrierten Geräten außerhalb von TestFlight, und Enterprise Profile für interne Verteilung außerhalb des App Stores.

Provisioning Profiles laufen ab, in der Regel nach einem Jahr, und müssen erneuert werden. Das führt in der Praxis zu einem der häufigsten Code Signing-Probleme: Eine App, die monatelang problemlos gebaut wurde, schlägt plötzlich fehl, weil das Profile im Hintergrund abgelaufen ist. Xcode erneuert abgelaufene Profile bei manuellem Signing automatisch, sofern "Automatically manage signing" aktiviert ist - bei CI-Pipelines und EAS-Builds übernimmt das die jeweilige Credentials-Verwaltung, weshalb ein Blick in den Ablaufstatus vor größeren Releases sinnvoll ist.

{
  "build": {
    "production": {
      "ios": {
        "credentialsSource": "remote",
        "distribution": "store"
      }
    }
  },
  "submit": {
    "production": {
      "ios": {
        "appleId": "developer@example.com",
        "ascAppId": "1234567890"
      }
    }
  }
}

4. Android Keystores und Signing Configs

Android verzichtet auf ein zentrales Zertifikatsystem wie Apple und setzt stattdessen auf selbst erzeugte Keystores. Ein Keystore ist eine Datei, die einen privaten Schlüssel und ein selbstsigniertes Zertifikat enthält, mit dem jede APK oder jedes AAB signiert wird. Für Code Signing unter Android gilt: Der Keystore, mit dem die erste Version einer App im Play Store veröffentlicht wurde, muss für alle zukünftigen Updates wiederverwendet werden - Google prüft bei jedem Upload, ob die Signatur zum ursprünglichen Zertifikat passt. Geht der Keystore verloren, kann die bestehende App-Identität im Play Store ohne Googles Unterstützung nicht mehr aktualisiert werden.

Seit der Einführung von Play App Signing hat sich das Risiko entschärft: Entwickler laden ihre Apps mit einem Upload Key signiert hoch, Google signiert das finale Paket intern mit einem separaten App Signing Key, der sicher bei Google verwahrt wird. Geht der Upload Key verloren, lässt sich über den Play Console Support ein neuer Upload Key hinterlegen, ohne die App-Identität zu verlieren. Für React Native Projekte mit Expo übernimmt EAS diesen kompletten Vorgang inklusive Keystore-Erzeugung und -Speicherung, was das manuelle Handling von `.jks`-Dateien in den meisten Teams überflüssig macht.

# Generate an Android keystore manually (only needed for non-EAS workflows)
keytool -genkeypair -v \
  -keystore release.keystore \
  -alias upload \
  -keyalg RSA -keysize 2048 -validity 10000

# Inspect an existing keystore's fingerprint (SHA-256), useful for
# verifying it matches the one registered in Play App Signing
keytool -list -v -keystore release.keystore -alias upload

5. EAS Credentials: Signing automatisch verwalten lassen

Der EAS Credentials Manager (`eas credentials`) ist für die meisten React Native und Expo Teams heute der pragmatischste Weg, Code Signing zu betreiben. Für iOS generiert er auf Wunsch automatisch Zertifikate und Provisioning Profiles, registriert Testgeräte für Ad-Hoc-Builds und speichert private Schlüssel verschlüsselt in Expos Infrastruktur. Für Android erzeugt er Keystores oder importiert bestehende, und verknüpft sie direkt mit dem jeweiligen Build-Profil in `eas.json`. Der große Vorteil: Entwickler müssen sich nicht mehr manuell durch das Apple Developer Portal klicken, um ein abgelaufenes Profile zu erneuern.

Trotzdem bleibt Code Signing über EAS kein Blackbox-Prozess. Mit `eas credentials` lässt sich jederzeit einsehen, welches Zertifikat, welches Profile und welcher Keystore aktuell für ein Build-Profil aktiv ist, und bestehende Credentials lassen sich exportieren, falls ein Team später auf eine andere CI-Lösung wechselt. Für Teams mit mehreren Apps oder mehreren App-Varianten (etwa Staging und Production als getrennte Bundle IDs) empfiehlt es sich, die Credentials pro Build-Profile in `eas.json` explizit zu benennen, damit nie versehentlich ein Staging-Zertifikat in einem Production-Build landet.

6. Fastlane match: Zertifikate im Team synchronisieren

Fastlane `match` verfolgt einen anderen Ansatz als EAS Credentials: Es speichert Zertifikate, private Schlüssel und Provisioning Profiles verschlüsselt in einem privaten Git-Repository (oder alternativ in einem Cloud-Storage-Bucket) und synchronisiert sie über eine gemeinsame Passphrase zwischen allen Team-Mitgliedern und CI-Runnern. Für Teams, die ihre CI-Pipeline selbst betreiben - etwa mit GitHub Actions oder GitLab CI statt EAS Build - ist `match` die etablierte Lösung, um Code Signing reproduzierbar zu halten, ohne dass jeder Entwickler eigene lokale Zertifikate erzeugt.

Der entscheidende Vorteil von `match` gegenüber individuell erzeugten Zertifikaten pro Entwickler: Es gibt pro Umgebung (Development, Ad Hoc, App Store) genau einen Satz an Credentials, der von allen geteilt wird. Das reduziert die Anzahl aktiver Zertifikate im Apple Developer Account drastisch - Apple begrenzt die Anzahl gleichzeitig gültiger Distribution-Zertifikate ohnehin auf drei. Der Nachteil: Das Match-Repository selbst wird zu einem kritischen, gut abzusichernden Asset, dessen Passphrase niemals im Klartext in einer Pipeline-Konfiguration landen darf.

// Fastfile: sync iOS signing credentials from the match repository
// before building, so CI never generates its own certificates
platform :ios do
  lane :beta do
    match(
      type: "appstore",
      readonly: is_ci,
      app_identifier: "com.example.myapp"
    )
    build_app(scheme: "MyApp", export_method: "app-store")
    upload_to_testflight
  end
end

7. Manuelles Signing in Xcode: Wann es noch sinnvoll ist

Trotz EAS und Fastlane bleibt manuelles Code Signing direkt in Xcode für einige Szenarien relevant, etwa beim Debuggen nativer Module, die einen eigenen Xcode-Workspace erfordern, oder in kleinen Teams ohne CI-Infrastruktur. Xcode bietet dafür zwei Modi: "Automatically manage signing", bei dem Xcode selbstständig Zertifikate und Profile über den angemeldeten Apple-Account erzeugt und erneuert, und manuelles Signing, bei dem Entwickler ein konkretes Provisioning Profile und Zertifikat explizit auswählen.

Automatisches Signing ist für einzelne Entwickler bequem, wird aber in Teams schnell unübersichtlich, weil jeder Entwickler potenziell eigene Development-Zertifikate erzeugt, die sich gegenseitig überschreiben können. Für Projekte, die parallel mit EAS oder Fastlane arbeiten, ist es daher sinnvoll, in Xcode manuelles Signing zu aktivieren und explizit dieselben Profile zu referenzieren, die auch die CI-Pipeline nutzt - so bleibt Code Signing zwischen lokaler Entwicklung und automatisierten Builds konsistent, statt zwei parallele, sich widersprechende Zertifikatsysteme zu betreiben.

8. Typische Signing-Fehler und wie man sie behebt

Die häufigste Fehlermeldung bei Code Signing-Problemen lautet sinngemäß "No signing certificate found" oder "Provisioning profile doesn't match the entitlements file". In den meisten Fällen steckt eine von drei Ursachen dahinter: Das Provisioning Profile ist abgelaufen, die App ID im Profile stimmt nicht mit dem Bundle Identifier im Xcode-Projekt überein, oder die Entitlements der App (etwa Push Notifications oder App Groups) sind im Profile nicht freigeschaltet. Ein Blick in den Apple Developer Account, Bereich Certificates, Identifiers & Profiles, zeigt meist sofort, welches der drei Probleme vorliegt.

Ein zweiter häufiger Fehler betrifft die Team ID: Wechselt ein Projekt zwischen mehreren Apple Developer Accounts, etwa von einem persönlichen zu einem Firmen-Account, bleiben oft alte Team-ID-Referenzen in der Xcode-Projektdatei zurück. Das Code Signing schlägt dann fehl, obwohl alle Zertifikate im neuen Account gültig sind. Der dritte klassische Fall ist ein abgelaufenes Push-Zertifikat, das getrennt vom App-Zertifikat verwaltet wird und leicht übersehen wird, wenn Push Notifications erst nachträglich zur App hinzugefügt wurden.

// build.gradle (app module): signing config referencing a keystore
// via environment variables, so the keystore itself never lives in git
android {
    signingConfigs {
        release {
            storeFile file(System.getenv("ANDROID_KEYSTORE_PATH") ?: "release.keystore")
            storePassword System.getenv("ANDROID_KEYSTORE_PASSWORD")
            keyAlias System.getenv("ANDROID_KEY_ALIAS")
            keyPassword System.getenv("ANDROID_KEY_PASSWORD")
        }
    }
    buildTypes {
        release {
            signingConfig signingConfigs.release
        }
    }
}

9. Vergleich: Manuelles Signing, Fastlane match und EAS Credentials

Die Wahl der richtigen Code Signing-Strategie hängt stark von Teamgröße, CI-Infrastruktur und davon ab, ob ein Projekt auf Expo/EAS oder eine eigene Build-Pipeline setzt. Die folgende Übersicht vergleicht die drei gängigsten Ansätze entlang der Kriterien, die in der Praxis am häufigsten den Ausschlag geben.

Für die meisten neuen React Native Projekte, die ohnehin auf Expo und EAS Build setzen, ist EAS Credentials der Weg mit dem geringsten Wartungsaufwand für Code Signing. Teams, die aus regulatorischen oder historischen Gründen eine eigene CI-Infrastruktur betreiben müssen, fahren mit Fastlane match zuverlässiger, weil sie die volle Kontrolle über das Credentials-Repository behalten. Manuelles Signing in Xcode bleibt eine sinnvolle Ergänzung für lokale Entwicklung, sollte aber nicht die primäre Strategie für Produktions-Releases sein.

10. Zusammenfassung

Code Signing für React Native Apps folgt auf iOS und Android unterschiedlichen, aber klar strukturierten Regeln. Auf iOS bilden Zertifikat, App ID und Provisioning Profile gemeinsam die gültige Signing-Konfiguration - fehlt eines der drei Elemente oder ist es abgelaufen, schlägt der Build fehl. Auf Android übernimmt ein selbst erzeugter Keystore diese Rolle, abgesichert durch Play App Signing, das den kritischen App Signing Key sicher bei Google verwahrt. EAS Credentials automatisiert beide Systeme für Expo-Projekte nahezu vollständig, während Fastlane match für Teams mit eigener CI-Infrastruktur die etablierte Alternative bleibt.

Der größte Hebel gegen wiederkehrende Signing-Probleme ist, frühzeitig eine einzige, dokumentierte Strategie festzulegen, statt manuelles Xcode-Signing, EAS Credentials und Fastlane match parallel und unkoordiniert im selben Projekt zu betreiben. Wer Code Signing als festen Bestandteil der Release-Pipeline behandelt und Ablaufdaten von Zertifikaten und Provisioning Profiles aktiv im Blick behält, vermeidet die meisten kurzfristigen Build-Ausfälle vor wichtigen Releases.

11. FAQ: Code Signing für React Native Apps