Notarisieren von Mac Apps

App in erster Version fertig - nice! Jetzt gehts an den Release. Damit auch andere die App ohne Schwierigkeiten und Warnungsmeldungen öffnen und benutzen können gibt es mehrere Schritte die zu verfolgen sind:

1. Produktions-Build der App

2. Notarisieren

3. Hosten der `.dmg` Files oder Einreichung im App Store

Bevor wir zu den einzelnen Secrets kommen, lohnt sich ein Blick darauf, warum es sie überhaupt braucht – denn ohne das Verständnis von Signierung und Notarisierung sind die IDs nur eine Sammlung kryptischer Zeichenketten.

Warum das alles? Gatekeeper, Signierung und Notarisierung

Seit macOS Catalina prüft Gatekeeper jede App, die aus dem Internet geladen wurde, bevor sie zum ersten Mal startet. Lädt jemand eine .dmg von deiner Website und die App ist nicht ordentlich signiert und notarisiert, bekommt er im besten Fall die Meldung „… kann nicht geöffnet werden, da Apple sie nicht auf Schadsoftware überprüfen konnte" – im schlechtesten Fall lässt sich die App gar nicht öffnen. Für eine App, die man verteilen möchte, ist das ein K.-o.-Kriterium.

Drei Begriffe muss man dafür auseinanderhalten:

1. Code Signing (Signierung)

Beim Signieren wird die App mit deinem Developer-ID-Zertifikat kryptografisch unterschrieben. Das erfüllt zwei Zwecke:

• Identität – macOS kann belegen, dass die App wirklich von dir (deinem Apple-Developer-Team) stammt.

• Integrität – jede nachträgliche Veränderung an der App bricht die Signatur, macOS erkennt Manipulationen.

Signiert wird mit dem Kommandozeilenwerkzeug codesign. Wichtig: Für die spätere Notarisierung muss die App mit Hardened Runtime signiert werden (codesign --options runtime). Das ist eine Reihe von Sicherheitsvorkehrungen zur Laufzeit (kein Code-Injection, keine unsignierten Bibliotheken usw.), die Apple zwingend voraussetzt.

2. Notarisierung (Notarization)

Signieren allein reicht Gatekeeper nicht. Zusätzlich muss die App notarisiert werden. Dabei lädst du die signierte App zu Apples Notary Service hoch. Apple prüft sie automatisiert (kein Mensch, keine inhaltliche Review wie im App Store!) auf:

• gültige Signatur mit einem Developer-ID-Zertifikat,

• aktivierte Hardened Runtime,

• bekannte Schadsoftware.

Läuft die Prüfung durch, stellt Apple ein Notarization-Ticket aus. Ab diesem Moment vertraut Gatekeeper der App. Die Notarisierung sagt also nicht aus, dass deine App gut oder funktional ist – nur, dass sie sauber signiert und frei von bekannter Malware ist.

Das moderne Werkzeug dafür ist notarytool (der ältere altool ist abgekündigt).

3. Stapling (Anheften des Tickets)

Nach erfolgreicher Notarisierung liegt das Ticket auf Apples Servern. Damit Gatekeeper es auch offline prüfen kann – etwa wenn der Nutzer beim ersten Start keine Internetverbindung hat – „heftet" man das Ticket mit xcrun stapler staple direkt an die .app bzw. .dmg an. Ohne Stapling fragt Gatekeeper das Ticket beim ersten Start online bei Apple ab; mit Stapling ist die App komplett autark.

Die Zutaten: Welche IDs, Zertifikate und Keys du brauchst

Für den Weg „Developer ID + Notarisierung" (Verteilung außerhalb des App Store, z. B. als .dmg von der eigenen Website) brauchst du sechs Dinge:

Voraussetzung für all das ist eine kostenpflichtige Mitgliedschaft im Apple Developer Program (99 $/Jahr).

Team ID

Die Team ID ist eine zehnstellige Kennung deines Developer-Teams (z. B. AB12CD34EF).

Fundort

developer.apple.com/account → Membership details → dort steht die Team ID.

Sie taucht außerdem in Klammern hinter dem Namen deines Signatur-Zertifikats auf (Developer ID Application: Deine Firma (AB12CD34EF)).

Developer ID Application-Zertifikat (.p12) + Passwort

Das ist das entscheidende Zertifikat für die Verteilung außerhalb des App Store. Achtung: Es gibt mehrere Zertifikatstypen – für unseren Zweck ist ausdrücklich „Developer ID Application" nötig (nicht „Apple Development", nicht „Apple Distribution").

Erstellen (falls noch nicht vorhanden):

• Bequem über Xcode: Xcode → Settings → Accounts → Team auswählen → Manage Certificates → + → Developer ID Application. Das Zertifikat landet direkt in deiner Login-Keychain.

• Alternativ manuell über developer.apple.com → Certificates: einen CSR (Certificate Signing Request) via Schlüsselbundverwaltung → Zertifikatsassistent → Zertifikat einer Zertifizierungsstelle anfordern erzeugen, hochladen, das .cer herunterladen und per Doppelklick installieren.

Exportieren als .p12:

1. Schlüsselbundverwaltung öffnen → Kategorie Meine Zertifikate.

2. Den Eintrag Developer ID Application: Deine Firma (TEAMID) suchen und das Aufklapp-Dreieck öffnen – darunter muss ein privater Schlüssel hängen. Ohne diesen privaten Schlüssel ist der Export wertlos, weil man damit nicht signieren kann.

3. Rechtsklick → Exportieren → Format .p12 → ein Passwort vergeben.

Dieses Passwort ist das Zertifikats-Passwort (in der CI unten APPLE_CERTIFICATE_PASSWORD).

Da GitHub Actions & Co. nur Text-Secrets speichern, die .p12 aber binär ist, kodiert man sie noch Base64:

Der so erzeugte Text ist das eigentliche Zertifikat-Secret (APPLE_CERTIFICATE); in der CI wird es vor dem Import wieder mit base64 --decode zurückverwandelt.

App Store Connect API Key (Key ID, Issuer ID, .p8)

notarytool muss sich gegenüber Apple authentifizieren. Der moderne, CI-freundliche Weg dafür ist ein App Store Connect API Key (die Alternative – Apple-ID + app-spezifisches Passwort – siehe weiter unten).

Fundort & Erstellung: App Store Connect → Users and Access → Tab Integrations → App Store Connect API → Team Keys → Generate API Key. Als Rolle genügt Developer, das reicht für die Notarisierung.

Nach dem Erstellen bekommst du drei Dinge:

• Key ID – die Kennung des neuen Schlüssels (APP_STORE_CONNECT_KEY_ID).

• Issuer ID – steht oben über der Schlüsselliste, gilt für alle Keys des Teams (APP_STORE_CONNECT_ISSUER_ID).

• AuthKey_<KEYID>.p8 – die private Schlüsseldatei. Nur ein einziges Mal herunterladbar! Verlierst du sie, musst du einen neuen Key erzeugen. Ihr kompletter Inhalt (inklusive der -----BEGIN PRIVATE KEY------ Zeilen) ist das Secret APP_STORE_CONNECT_PRIVATE_KEY.

Der Ablauf beim Notarisieren

So greifen die Teile ineinander – im Prinzip genau die Schritte, die auch die CI-Pipeline automatisiert abfährt:

# 1. Signieren – mit Hardened Runtime und sicherem Zeitstempel

# 2. Zum Hochladen paketieren (App in ein ZIP, oder direkt die DMG nehmen)

# 3. An den Notary Service übergeben und auf das Ergebnis warten

# 4. Ticket anheften, damit Gatekeeper offline prüfen kann

# 5. Gegenprüfen

Bei einer .dmg wiederholt man Signieren, Notarisieren und Stapling für die DMG selbst – so ist sowohl der Datenträger als auch die enthaltene App sauber.

Ab in die CI: die Secrets bei GitHub Actions hinterlegen

In einem GitHub-Actions-Workflow werden die sechs Werte als Repository Secrets hinterlegt (Settings → Secrets and variables → Actions) und dann per Umgebungsvariable in die Signier-/Notarisier-Schritte gereicht. Bequem geht das auch per CLI – gh secret set NAME (ohne Wert) fragt den Wert interaktiv ab und hält ihn so aus der Shell-History heraus:

Signierung vs. Notarisierung vs. App Store – wann was?

Die Begriffe werden gern verwechselt. Es gibt zwei grundsätzlich verschiedene Verteilwege, und sie brauchen unterschiedliche Zertifikate:

• Developer ID + Notarisierung (dieser Artikel): Du verteilst die App selbst als .dmg/.app – über deine Website, einen Download-Link, einen internen Server. Zertifikat: Developer ID Application. Du notarisierst selbst. Gatekeeper öffnet die App ohne Warnung.

• App Store: Die App geht über App Store Connect zur Review und wird über den Store verteilt. Zertifikat: Apple Distribution / App Store. Eine eigene Notarisierung entfällt – der App-Store-Prozess erledigt das. Dafür kommt die inhaltliche Prüfung durch Apple hinzu.

Für ein Tool, das man Kolleg:innen oder Kund:innen einfach als Download in die Hand drücken will, ist der Developer-ID-Weg meist der richtige.

Häufige Stolpersteine

• .p12 ohne privaten Schlüssel exportiert. Nur mit privatem Schlüssel kann signiert werden. Vor dem Export in der Keychain das Aufklapp-Dreieck prüfen.

• .p8 verloren. Der API-Private-Key ist nur einmal herunterladbar. Ist er weg, hilft nur ein neuer Key.

• Zertifikatsname stimmt nicht mit dem Signatur-String überein. Die Signatur-Identität muss exakt dem Common Name des Zertifikats entsprechen. Prüfen mit security find-identity -v -p codesigning.

• Hardened Runtime vergessen. Ohne --options runtime (und --timestamp) lehnt der Notary Service die App ab.

• Nur die App, nicht die DMG notarisiert (oder umgekehrt). Beide Ebenen signieren, notarisieren und stapeln.

• Falsche Zertifikatssorte. „Apple Development" ist zum Entwickeln da, nicht zum Verteilen – für Notarisierung braucht es „Developer ID Application".

Anhang: die Variante ohne API Key

Statt des App Store Connect API Keys lässt sich notarytool auch mit Apple-ID + app-spezifischem Passwort + Team ID authentifizieren:

Das app-spezifische Passwort erzeugt man unter account.apple.com → Anmeldung & Sicherheit → App-spezifische Passwörter. Für automatisierte Pipelines ist der API Key aber die sauberere Wahl: kein persönliches Konto im Spiel, feingranular widerrufbar und ohne Kopplung an die Zwei-Faktor-Absicherung einer Apple-ID.