Apple Certificates Overview

Certificate files can be in .p12 file format as a private-public key pair. There are 2 main types of iOS certificates:

1. Apple Development: Used for development and testing.

The development certificates allow deploying apps to the developer devices (connected physically for testing and debugging) during the actual development process on Xcode.

The common practice is to generate this certificate automatically on Xcode, although manual generation is also available. Binaries built with a development certificate cannot be distributed.

2. Apple Distribution: Used for submitting applications to the App Store, or for Ad Hoc and Enterprise distribution. (Refer to the provisioning profiles section for the differences between these distribution types.)

In most cases, you will be using a distribution certificate with the combination of a provisioning profile to build and distribute apps in Appcircle.

There is a one-to-many relationship between certificates and provisioning profiles, so you may have multiple provisioning profiles associated with a single certificate.

info

For app builds, signing identities are not mandatory. For example, you can use unsigned apps to run on the simulator or on third-party platforms that resign your app, such as AWS Device Farm.

However, unsigned binaries cannot be installed on actual devices; therefore they cannot be used in the Appcircle Testing Distribution.

You can obtain your developer certificates and provisioning profiles from the Apple Developer Portal:

Security Verification

Security verification page to protect against malicious bots.

developer.apple.com

Using Appcircle Signing Identity module for Apple Certificates

Creating an Apple Certificate

With Appcircle’s advanced Signing Identity module, you can easily generate certificates without logging into your Apple Developer account and securely store these certificates in .P12 format within the Appcircle.

• To do this, navigate to the Apple Certificates section within the Signing Identity module. Then click Add new to create a certificate.

• In the Add a certificate panel, continue by selecting Create an Apple certificate.

• Appcircle requires an App Store Connect API Key associated with your account to create a certificate. If the API Key is not added to your Appcircle organization, you cannot proceed with the certificate creation process. For more information, please refer to the App Store Connect API Key documentation.

• After selecting the appropriate API Key, Appcircle requires a CSR (Certificate Signing Request) file to create an Apple certificate. With the option provided by Appcircle, you can select one created on Appcircle from the list. For more detailed information about the CSR creation process, please refer to the Generate Signing Request to Create Certificate section.

Create Certificate with CSR File

If you want to create a certificate, you can proceed by using the Select Certificate Signing Request from List option.

When this option is selected, all existing CSR files in Appcircle will be listed, prompting you to choose one. After selecting the relevant CSR file, the desired certificate type must be chosen. Optionally, a password can be specified, or the Auto Generate Password feature can be used to generate one automatically. If you do not have CSR file, please refer to the Generate Signing Request to Create Certificate section.

Generating Password

Adding a password during P12 export is completely optional. If you do not specify a password, the P12 file will be created without one. However, if you prefer for automatic password generation, be sure to record the password generated by Appcircle. Otherwise, you may encounter issues when using the provisioning file.

Creating Certificate Signing Request File

The Certificate Signing Request (CSR) file is required by Apple when creating a certificate. This file allows the user to generate a certificate, so it must be created in advance and provided as needed. Since this file can only be generated on a macOS operating system, it is unlikely to be created on other systems. Therefore, you can easily generate a CSR file using Appcircle’s Generate Signing Request to Create Certificates feature.

By correctly filling in the required parameters such as name, email, and country you can generate this file without needing a macOS operating system.

Generating CSR File

It is important that the information provided is accurate. Any errors in these details may prevent Apple from allowing the certificate generation process.

Creating P12 File Without Mac

To generate your iOS certificates, simply fill in your details and Appcircle will provide a CSR (certificate signing request) which you can use on Apple Developer Portal to generate your signing certificate.

• Create a CSR File

• Download your CSR file

• Go to the Apple Developer Portal and select "Certificates, IDs & Profiles" from the left menu, then click on "Certificates."

  

• Select the type of certificate you want to create. If you want to distribute to TestFlight, Ad-hoc or AppStore, you should select Apple Distribution. If you're creating a certificate for local development environment, you should select Apple Development.

• Upload the CSR file you have created on Appcircle

• Download your generated CER file from the Apple Developer portal

• Upload the CER file to the signing identities module by opening the ... menu of the CSR file under the Actions column and selecting Upload.

• Your CSR will now be converted to a P12 file as an iOS signing certificate. (Please note that the P12 file comes with an empty password.)

Uploading P12 Certificate

To upload your Apple Certificate, click Add new, select Upload certificate bundle (.p12) and upload your pre-obtained Apple Certificate file.

You can see a list of your created or uploaded certificates. Each certificate will display the certificate name, certificate type (development, ad-hoc, in-house, or app store distribution) along with expiration dates.

caution

If your password contains special characters such as $ and #, your workflow may fail with MAC verification failed during PKCS12 import message. If you receive such an error, please export your P12 file by removing that symbol.

Apple Certificate Expiration Notifications

You will be notified when an Apple Certificate is about to expire. You can see the expiration notification in the in-app notification window and optionally enable expiration notifications for Email, Slack, Microsoft Teams, etc.

Standard Schedule: Certificates already in the system 30+ days before expiration receive notifications at 30, 15, 7, 3, 1 days before expiration, plus expiring today.

Late Upload: Certificates uploaded with less than 30 days remaining before expiration get notifications starting from upload day, then continuing with the next applicable intervals from the standard schedule.

Manual Renew Certificate

Apple Certificates have a limited validity period and must be renewed before they expire to avoid interruptions in your build and distribution workflows. Appcircle allows you to manually renew an existing Apple Certificate directly from the Signing Identities module, so you can generate an up-to-date certificate without having to remove and reconfigure your current one.

• In order to manually renew an Apple Certificate, open the ... menu of the related certificate under the Actions column, select Renew, and choose Manual renew Apple certificate (.cer). Then select the App Store Connect API key that Appcircle will use for the renewal and click Next.

App Store Connect API Key

Renewing an Apple Certificate requires a valid App Store Connect API Key associated with your organization, just like creating a new certificate. If no API Key has been added to your Appcircle organization, the renewal process cannot be completed. For more information, please refer to the App Store Connect API Key documentation.

CSR File

Please remember that the CSR file must be generated on Appcircle in order to successfully renew the certificate. You can find detailed instructions on how to generate the CSR file in this document.

Apple Certificate Generate Limit

There are limits on the number of certificates that can be generated on Apple. These limits are restricted to 3 for Distribution and 2 for Development types. However, these limits may vary for create operations performed via the API. If Apple does not allow a create or renew operation via the API, a notification will appear on Appcircle.

• Appcircle requires certain inputs for the certificate you wish to renew. The purposes of these inputs are explained below.

  • Revoke This Certificate Before Renew: If you want to revoke the certificate you wish to renew on the Apple Developer Portal first, and then create a new certificate, you will need to enable this toggle. If you keep this toggle disabled, Appcircle creates the new certificate and leaves the old one valid on the Apple Developer Portal. In that case the new certificate counts against the Apple certificate creation limit described above. If you have already reached the limit for that certificate type, this toggle is not shown; instead, a warning states that the certificate will be revoked, and the renewal revokes it on the Apple Developer Portal to free a slot.
  • CSR File: Apple will not allow a certificate to be generated without a CSR file. Therefore, a CSR file must be selected.
  • Automatically Generate Password: Appcircle will automatically generate a random password if this toggle is enabled.
  • Password(Optional): When generating a certificate, you are prompted to set a password. This password is entirely optional, and the certificate will be generated without any issues even if you do not set one.

Renew Preview

Before performing the Appcircle renewal process, this panel provides the user with a preview and displays all the necessary information.

• Existing Certificate: This is the certificate currently in use. Once the renewal is confirmed, it is replaced by the new certificate and all associated provisioning profiles are affected. It is also permanently revoked on the Apple Developer Portal if the Revoke This Certificate Before Renew toggle is enabled.
• Replacement Certificate: This certificate will replace the existing one once the renewal is confirmed. All associated provisioning profiles are regenerated automatically.
• Affected Profiles Details: The profiles listed below will be affected after the renew operation. This may cause build failures and errors in automatic re-sign processes.

Affected Provision, Build and Re-sign Profiles

During the Appcircle certificate renewal process, it recreates all provisioning profiles associated with the certificates. Additionally, it directly replaces the old certificates used in the re-sign and build profiles with the new ones.

You do not need to regenerate these provisioning profiles manually. However, applications that were already built and distributed keep the profile they were signed with, so they must be rebuilt with the new certificate and profile and redistributed to be updated.

Renewing an Enterprise or Ad Hoc Distribution Certificate

Applications signed with an Enterprise (in-house) or Ad Hoc distribution certificate stop working on end-user devices as soon as that certificate is revoked on the Apple Developer Portal. Apple invalidates every app still signed with it, including versions that are already installed. Simply creating a new certificate does not affect them, but revoking the old one does.

For this reason, renew an Enterprise or Ad Hoc distribution certificate in the following order:

1. Renew the certificate with the Revoke This Certificate Before Renew toggle disabled, so the new certificate is created while the old one remains valid.
2. Build a new version of your applications with the new certificate and its regenerated provisioning profiles.
3. Distribute that new version and wait until your users have updated to it.
4. Only after every distributed application has been updated, revoke the old certificate from the Revoke Certificate action.

Do Not Revoke Before Redistributing

Revoking an Enterprise or Ad Hoc distribution certificate immediately renders all applications signed with it unusable, including the ones already installed on your users' devices. Never revoke the old certificate until the new build has been distributed and adopted.

Auto Renew Certificate

Instead of renewing an Apple Certificate manually before each expiry, you can let Appcircle renew it for you. When auto renew is enabled, Appcircle renews the certificate automatically a selected number of days before it expires, regenerates its provisioning profiles, and replaces the old certificate in your build, re-sign and distribution profiles, exactly like a manual renewal.

Availability

Certificate auto renewal is available on Appcircle Cloud starting from version 3.34.0.

Requirements

To enable auto renew for a certificate, the following are required:

• App Store Connect API Key: A valid App Store Connect API Key that Appcircle will use for every renewal.
• CSR file generated on Appcircle: Only CSR files generated on Appcircle can be selected. Uploaded CSR files are not listed.
• Eligible certificate: The certificate must be stored in Appcircle with its private key, must not be revoked or already superseded by a renewal, and must belong to your current organization. Certificates shared from a root organization cannot be configured in a sub-organization.

Enabling Auto Renew

1. Open the ... menu of the related certificate under the Actions column and select Renew.

2. Select Auto renew Apple certificate (.cer).

3. Turn on the Enable auto renew toggle.
4. Under Certificate signing request, select the CSR file. Then, under Lead time before expiry, choose how many days before the expiration date the certificate should be renewed: 1, 3, 5 or 7 days. The default is 5 days.

5. Click Next and review the Auto renew preview. It shows the selected certificate signing request, the lead time, the date the certificate will be renewed on and its new expiry date.
6. Click Save to enable auto renew.

The new certificate uses the same password as the current certificate, so no password input is needed for auto renewal.

Enabling Close to Expiry

If the selected lead time is longer than the remaining lifetime of the certificate, or the certificate has already expired, the setting is still accepted and the renewal is attempted within a few minutes. For an already expired certificate, Appcircle makes a single renewal attempt; if it fails, auto renew is turned off.

Auto Renew Status in the Certificate List

The certificate list contains an Auto renew column. Certificates with auto renew enabled display an Enabled tag followed by the scheduled renewal date. The expiration date of the certificate is shown in the Expires column.

Hover over the tag to see the scheduled renewal date.

How Auto Renewal Works

• The renewal runs on the scheduled day (expiration date minus the selected lead time) at 03:00 UTC.
• Auto renewal always revokes the old certificate on the Apple Developer Portal:
  • If the Apple certificate limit for that certificate type is full, the old certificate is revoked first to free a slot, then the new one is created.
  • If there is a free slot, the new certificate is created first and the old one is revoked afterwards.
• The old certificate is removed from the certificate list, and the new certificate takes its place.
• All provisioning profiles associated with the certificate are regenerated, and the certificate is replaced in build and re-sign profiles, the same way as in a manual renewal.
• The new certificate inherits the auto renew settings (CSR file and lead time), so it is renewed automatically again before its own expiry.

Enterprise and Ad Hoc Distribution Certificates

Because auto renewal always revokes the old certificate, applications signed with an Enterprise (in-house) or Ad Hoc distribution certificate stop working on end-user devices as soon as the renewal completes, including versions that are already installed.

Do not enable auto renew for these certificates unless you are sure that no distributed application still depends on the old certificate. Follow the manual renewal order for them instead.

Affected Profiles and Distributed Applications

Applications that were already built and distributed keep the profile they were signed with. They must be rebuilt with the new certificate and profile and redistributed to be updated.

Failed Renewals

• Temporary errors (for example, Apple services being unavailable or rate limiting) are retried automatically every 6 hours until the certificate expires.
• Permanent errors (for example, an invalid or unauthorized API key, a missing CSR file, or an error returned by Apple) stop the retries, and auto renew is turned off for the certificate.
• If the certificate expires without a successful renewal, auto renew is turned off.

In every failure case, an Apple Certificate Auto Renew Failed notification is sent, stating the reason and whether another attempt will be made. If auto renew was turned off, renew the certificate manually.

When Auto Renew Is Turned Off Automatically

Auto renew depends on the API key, the CSR file and the certificate itself. Appcircle turns auto renew off immediately, and sends an Apple Certificate Auto Renew Turned Off notification, when:

• The App Store Connect API Key used for the renewal is removed.
• The App Store Connect API Key is no longer shared with the organization that owns the certificate.
• The CSR file used for the renewal is deleted.
• The certificate is revoked.

Restoring the dependency (for example, sharing the API key again) does not re-enable auto renew. Enable it again from the Renew action.

Deleting a CSR File Used by Auto Renew

When you try to delete a CSR file that is used by auto renew, Appcircle shows a warning listing the affected certificates. You can cancel, or force the deletion. If you force it, auto renew is turned off for all affected certificates.

Changing or Disabling Auto Renew

Once auto renew is enabled, the Renew panel of the certificate shows Configure certificate auto-renewal instead of Auto renew Apple certificate (.cer).

To change the CSR file or lead time, open the ... menu of the certificate, select Renew > Configure certificate auto-renewal, update the settings, click Next and then Save.

To disable auto renew, open the same screen, turn off the Enable auto renew toggle and click Save. The Auto renew column of the certificate shows - again.

Manual Renewal While Auto Renew Is Enabled

Manual renewal is not available for a certificate while auto renew is enabled, so Manual renew Apple certificate (.cer) appears disabled on the Renew panel. To renew it manually, disable auto renew first.

Notifications and Activity Logs

Auto renew events are delivered through the in-app notification window and, if configured, through Email, Slack and Microsoft Teams notifications:

• Apple Certificate Auto Renew On: Auto renew was enabled or its settings were updated. Shows the lead time, the next renewal date and the expiration date.
• Apple Certificate Auto Renew Turned Off: Auto renew was turned off, with the reason.
• Apple Certificate Auto Renew Failed: A renewal attempt failed, with the reason and the next attempt time, if any.

A successful automatic renewal is reported as an automatically renewed certificate. These events are also recorded in the Signing Identities activity logs.

Revoke Certificate

On Appcircle, you can revoke your certificates directly without having to go to the Apple Developer Portal. To do this, open the ... menu of the certificate under the Actions column and select Revoke.

Revoke Certificate

Please keep in mind that if a certificate is revoked, this does not mean it will be automatically renewed. The revocation process is irreversible and permanently deletes the existing certificate from your Apple Developer account. Binaries signed with the revoked certificate will no longer be valid and will need to be signed with a new certificate. Before revoking your certificates, make absolutely sure that this will not affect your workflows.

Deleting a Certificate

To delete an Apple Certificate, click the ... button and select the Delete option.

info

Certificates deleted on Appcircle will only be removed from Appcircle and will not affect those on Apple Developer account.

Sharing Apple Certificates

Root Organization users have the ability to share their Apple Certificates with Sub-Organization users.

Shared certificates can be used in Sub-Organizations just like locally created or uploaded certificates.

How to Share Apple Certificates

1. Navigate to the Apple Certificates Section
   Go to the Signing Identity module and open the Apple Certificates section.

2. Open Certificate List
   Locate the certificate you want to share from the list.

3. Select the Certificate
   Open the ... menu under the Actions column for the selected certificate and select Share.

4. Configure Sharing Settings
   In the Share panel:

• Enable Share with all sub-organizations to automatically share the certificate with all existing and newly created sub-organizations.
• Alternatively, manually select specific sub-organizations that should have access.

5. Save Sharing Configuration
   Click Share to apply the configuration.

Behavior in Sub-Organizations

• Shared certificates will be visible and selectable in Sub-Organizations as if they were their own.
• These certificates will be marked with a Shared tag on Root Organization and Inherited tag on Sub Organizations' certificate list.
• Sub-Organization users cannot edit, rename, or delete shared certificates.

tip

• When Share with all sub-organizations is enabled, the certificate will automatically be available in newly created sub-organizations as well.

caution

• Any updates or deletions made in the Root Organization will directly affect all Sub-Organizations using the shared certificate.