configure_development_certificate.rst (4337B)
1 Configure Development Certificate 2 ============================================================= 3 4 To locally test macOS builds that are signed like production builds and can use 5 restricted entitlements, you need a valid development signing certificate and 6 provisioning profile from Mozilla’s Apple Developer account. 7 8 Before you begin, make sure your Apple Developer account has been added to 9 Mozilla’s Apple Developer team. If you don’t have access to Mozilla’s Apple 10 Developer account, you can `request access through Bugzilla 11 <https://bugzilla.mozilla.org/enter_bug.cgi?product=App%20Stores&component=App%20Store%20Access>`__. 12 You'll also need to have Xcode installed and be signed in to your Apple ID 13 within Xcode. 14 15 To obtain the necessary certificate and provisioning profile, we’ll create a 16 simple Xcode project. This project doesn’t need to be functional, its purpose 17 is only to trigger Xcode into automatically creating and downloading the 18 required signing certificate and provisioning profile. Once set up correctly, 19 Xcode will add the development certificate to your local keychain (visible in 20 Keychain Access) and download the provisioning profile for you. 21 22 Step 1: Set Up a macOS App Project in Xcode 23 ------------------------------------------- 24 25 Begin by launching Xcode and creating a new project. Choose ``App`` under the 26 macOS tab and click ``Next``. On the next screen, fill out the form by setting 27 the Product Name to ``nightly``, and under Team, select Mozilla Corporation. 28 If it doesn’t appear, make sure you're logged into your Apple ID, select 29 ``Add Account``, and choose Mozilla Corporation from the available teams. 30 For the Organization Identifier, enter ``org.mozilla``. Leave the default 31 options for Interface and Language (Storyboard and Objective-C, respectively). 32 After clicking ``Next``, choose a location for your project and create it. 33 34 .. image:: ../img/new_xcode_project.png 35 36 Step 2: Enable Automatic Signing 37 -------------------------------- 38 39 Once your project is set up, select it in the left sidebar of Xcode. Then go to 40 the ``Signing & Capabilities`` tab. 41 42 Ensure that ``Automatically manage signing`` is checked, and verify that the 43 Team is set to Mozilla Corporation. Then, in the ``Signing & Capabilities`` 44 tab, click the ``+`` Capability button and add both 45 ``Web Browser Public Key Credential Requests`` and ``App Groups``. 46 Adding these capabilities prompts Xcode to download a development certificate, 47 private key (which you can view in Keychain Access), and a provisioning profile 48 that includes the necessary entitlements. 49 50 .. image:: ../img/add_capability.png 51 52 After adding the required capabilities, the ``Signing & Capabilities`` screen 53 should update to show a signing certificate under the macOS section, indicating 54 that Xcode has downloaded the provisioning profile. 55 56 .. image:: ../img/cert_added.png 57 58 To verify that the certificate has been installed correctly, open Keychain 59 Access. In the login keychain under My Certificates, you should see the 60 development certificate that Xcode added. This confirms that your signing 61 identity is set up correctly. 62 63 64 Step 4: Install the Provisioning Profile 65 ---------------------------------------- 66 67 Start by navigating to the directory where Xcode stores user provisioning 68 profiles: 69 70 .. code-block:: shell 71 72 cd ~/Library/Developer/Xcode/UserData/Provisioning\ Profiles 73 74 You can open the folder in Finder by running: 75 76 .. code-block:: shell 77 78 open . 79 80 From there, double-click the relevant provisioning profile file and select 81 install. 82 83 To confirm the installation, open System Settings, navigate to General > 84 Device Management, and look for the profile under the Provisioning section. 85 86 Using the Certificate Name for Code Signing 87 ------------------------------------------------- 88 89 In Keychain Access, the certificate appears under My Certificates with a name 90 like: 91 92 ``Apple Development: Your Name (XXXXXXXXXX)`` 93 94 This name is the certificate’s Common Name. The string in parentheses, for 95 example ``5R6WGP5CFT`` in the image above, acts as an identifier for 96 the certificate and can be passed to the ``./mach macos-sign`` command using the 97 ``-s`` option for code signing: 98 99 .. code-block:: shell 100 101 ./mach macos-sign -s 5R6WGP5CFT 102 103 For full signing instructions, see 104 :doc:`Signing Local macOS Builds <../signing/signing_macos_build>`.