1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
|
=====
macOS
=====
Overview
========
In this tutorial, we'll learn how to generate a macOS code signing identity,
which is required to distribute your application across MacOS and iOS devices.
We will specifically focus on generating a `Developer ID Application identity
<https://developer.apple.com/developer-id/>`__, which is used to distribute a
*macOS application outside of the Mac App store*. However, the procedure for
creating all other types of identities is exactly the same. Once you familiarize
yourself with the general process, you'll be able to create identities required
to upload applications to the Mac or iOS App stores.
Generating a Code Signing identity
==================================
Getting the code signing identity will require five main steps, which you will
be guided through in this tutorial:
1. Enrolling in the Apple Developer program
2. Generating a Certificate Signing Request on Keychain Access
3. Creating a Developer ID Application Certificate
4. Accessing the details of the Certificate on your Terminal
5. Anticipating potential issues with the identity in the future
.. _apple-dev-enroll:
Enrolling in the Apple Developer program
----------------------------------------
You can enroll in the Apple Developer program either as an individual, or as an
organization. In both cases, you'll have to follow the instructions on the `Apple
Developer website <https://developer.apple.com/programs/enroll/>`__.
Once you click "Start Enrollment Now" at the bottom of the page, you can either sign in
with your existing Apple ID or alternatively, create a new one:
.. image:: images/AppleID.png
:width: 300
There are two types of Apple Developer account - a *personal* account, and a *business*
account. If you use your personal Apple ID to create an Apple Developer account,
converting it to a business account later can be painful. If you use your personal Apple
ID to create a business account, extracting your personal credentials later can also be
painful.
As part of the registration procedure, you'll have to pay a **$99 fee**, which will be
charged on an annual basis.
.. admonition:: Fee waivers
If you're registering as a non-profit organization, an educational institution or a
government entity, you may be eligible for a fee waiver, which you can read more about
`here <https://developer.apple.com/help/account/membership/fee-waivers/>`__.
Generating a certificate request on Keychain Access
---------------------------------------------------
Now that you're set up with an Apple Developer ID, it's time to create a
*certificate request*, which you'll then use to generate a valid Developer ID
certificate.
First, open the Keychain Access application on your Mac. At the top left of your
screen, click ``Keychain Access`` > ``Certificate Assistant`` > ``Request a
Certificate From a Certificate Authority``:
.. image:: images/Keychain_request1.png
:width: 500
A Certificate Assistant window should open up, looking similar to this one:
.. image:: images/Keychain_request2.png
:width: 500
* In the field ``User Email Address``, type the email address associated with
your Apple Developer Account (e.g. ``jane@example.com``).
* ``Common Name`` should refer to the name with which you registered to the
Apple Developer program (e.g. ``Jane Doe``).
* The field ``CA Email Address`` can be left empty.
* Make sure that you choose ``Saved to Disk`` in the ``Request is`` field.
* Click "Continue", and save your Certificate Signing Request somewhere on your
local machine. The saved certificate request should be of the format
``example.certSigningRequest``.
As documented by `Apple
<https://help.apple.com/xcode/mac/current/#/dev97211aeac>`__, this procedure
creates not only the file you have just saved, but also a private key in your
Keychain, which will establish the validity of your actual Developer ID
Application certificate later on.
Creating a Developer ID Application Certificate
-----------------------------------------------
Once you have saved the certificate request, head to the `Apple Developer
website <https://developer.apple.com/>`__, log in, and click "Certificates,
Identifiers and Profiles":
.. image:: images/Certificates_Identifiers_Profiles.png
:width: 500
When you land in the Certificates section, click the "+" symbol to create a new
certificate:
.. image:: images/Create_certificate.png
:width: 500
In the next page, you'll have to choose the type of certificate you want to
generate. In the Software section, choose the option of **"Developer ID
Application"**. **It's very important you choose the right type of
certificate**.
Later on, if you want to generate another code signing certificate for other purposes,
such as uploading your application the App store, you'll choose a different type of a
certificate on this page.
.. image:: images/Choose_developerID_application.png
:width: 500
.. note::
If you've been registered as an organization, there's a chance that
the option to choose the Developer ID Application certificate is unavailable.
This may happen if you're not assigned the role of the `Account Holder
<https://developer.apple.com/documentation/security/notarizing-macos-software-before-distribution>`__.
You can access and change these roles using `App Store Connect
<https://appstoreconnect.apple.com/login>`__.
Select "Developer ID Application" and click "Continue". In the next window,
click "Choose file" and upload the Certificate Signing Request you have just
generated on your Keychain:
.. image:: images/Upload_certificate_request.png
:width: 500
Once you click "Continue", Apple will generate your Developer ID Application
Certificate. Click the "Download" button and save the certificate on your local
machine:
.. image:: images/Download_certificate.png
:width: 500
The certificate should be of the format ``example.cer``. Once you download it,
double-click to install it in your Keychain Access.
If you now open your Keychain, selected the ``login`` keychain on
the left-hand side, and select the ``My Certificates`` tab, you should see a
certificate with the title "Developer ID Application: <your name>".
Click on the certificate and make sure you see a note that reads ``This
certificate is valid``.
.. image:: images/Valid_certificate.png
:width: 500
.. note::
In this screenshot, the certificate details have been redacted. Your
certificate should show expiration details, trust chains, and other
details about you, the certificate issuer (Apple), and the certificate.
Congratulations! You've just successfully installed the Developer ID Application
certificate.
.. admonition:: Keep this certificate safe!
The *specific type* of the certificate you have just created is quite
precious, and you should make sure to keep it safe. A single Developer ID
Application Certificate can be used to `sign, notarize and distribute
multiple applications <https://developer.apple.com/forums/thread/657993>`__
outside of the Mac App store, which is why a `very limited number of them
<https://help.apple.com/xcode/mac/current/#/dev3a05256b8>`__ can be created
on a particular Developer Account. You should consider making a backup copy,
which will require you to export the certificate together with the associated
private key from the Keychain. The procedure for doing so is `documented by
Apple
<https://support.apple.com/guide/keychain-access/import-and-export-keychain-items-kyca35961/mac>`__.
Other types of Code Signing identities
======================================
If you want to distribute a macOS application outside the macOS App Store, a Developer
ID Application Certificate is all you require. However, there are other types of
certificates for other types of apps, and other modes of app distribution:
* A **Developer ID Installer** certificate is needed if you're going to distribute a
``.pkg`` installer of your application.
* A **Mac App Distribution** certificate is used to sign your app when it's going to be
submitted to the Mac App Store.
* A **Mac Installer Distribution** certificate is used to sign the installer package you
submit to the Mac App Store.
The process for generating these certificates is the same as the process used to
generate a Developer ID Application Certificate; select the appropriate option
when generating the certificate on the Apple Developer website.
When a certificate is generated, it is associated with a Team ID, representing the
organization or individual that requested the certificate. If you need to use multiple
certificates when signing an app (for example, when signing a ``.pkg`` installer), you
must ensure that the certificates all come from the same Team ID - you can't sign an app
with a certificate from one team, then sign the installer with a certificate for a
different team.
Next steps
==========
Now you can use the certificate to sign and notarize your application with the
:doc:`briefcase package </reference/commands/package>` command.
When you invoke :doc:`briefcase package </reference/commands/package>`, you will be
prompted to select the code signing certificate you want to use from the certificates
that are installed. Once you select a certificate, Briefcase will output the command
line invocation to select that certificate for unattended installation.
|
