How to Troubleshoot APNs

Not long ago, a Kandji customer reached out because they’d received a notification that they needed to renew their certificate for the Apple Push Notification Service (APNs). But when they tried to do so, they found they couldn’t. The problem: The admin who’d originally set up the certificate was no longer with the company. Without his Apple ID, they couldn’t renew.

Renewing APNs certificates is a critical chore for Mac admins. But it’s a picky one: You have to do it on time, before the yearly expiration date. And you have to use the same Apple ID you used to create the certificate in the first place. Fail either of those requirements and your APNs certificate can expire, and that magic triangle of communication between your MDM solution, Apple, and your devices is at least temporarily broken—meaning MDM can no longer manage your devices. Worse yet: you might have to re-enroll every device.

These are all preventable problems. Here’s how to ensure they don’t happen to you, and what you can do if they do.

How to Renew an APNs Certificate

Apple Push Notification Service (APNs) is an integral component of Apple’s MDM infrastructure. MDM solutions use APNs to send notifications—via persistent, secure connections—to devices when there are MDM commands pending for them. The devices then contact the MDM solution to receive those commands. For those communications to happen, you must provide an Apple-issued APNs certificate to your MDM solution. 

To create a new certificate, you first need to download a Certificate Signing Request (CSR) from your MDM solution. (Here, for example, is how you do so in Kandji.) CSR in hand, you then go to the Apple Push Certificates Portal, click Create a Certificate, agree to the Terms of Use, and upload your CSR. That will create a new push certificate (in the form of a PEM file), which you can then upload to your MDM solution.

APNs certificates need to be renewed every year. The process for doing so is very similar to the process of creating a new one: You download the CSR, upload it at the push certificates portal, collect the PEM, and upload that to your MDM solution, and you should be good to go.

But, as we noted above, two things can—and not infrequently do—go wrong when it comes to renewing them: You don’t renew in time. Or you can’t renew because you don’t have the right Apple ID. Let’s take a look at what you can do in either case.

Renew Your APNs Certificate in Time

In the normal course of events, Apple sends out email reminders to the APNs account holder 30, 10, and 1 day(s) ahead of certificate expiration. You will also likely get a notification from your MDM solution informing you that your certificate is expiring and you need to renew it. (For example, Kandji displays a banner in the Kandji web app when a certificate is approaching its expiration date.)

But notifications, no matter how persistent, are often ignored. It’s vital that someone is monitoring the email addresses associated with that account. (But that can go wrong, too—see below.) So we also strongly recommend that you set yourself a reminder six and four months ahead of your next expiration date—just to be sure you renew in a timely fashion. Nothing prevents you from renewing your APNs certificate at any time, so why take the risk that the next expiry date lands during a holiday or vacation?

Renew Your APNs Certificate with the Right Apple ID

In order to download a certificate from the push certificates portal, you need to sign in with an Apple ID. The recommended practice is to use an organizationally-controlled Managed Apple ID for this purpose. But it’s still common for an IT team member who’s been tasked with downloading a certificate to use a personal Apple ID (also referred to as a consumer Apple ID) instead. If that happens, and if that team member should leave the organization, you’ll have no way of signing in to renew.

That’s why the first rule of APNs is: Use a Managed Apple ID to get your certificate. It’s best to use a dedicated ID, with a name that doubles as a clear label—such as APNS@yourdomain.com—so it isn’t deleted inadvertently. 

Use a Staff Role

We also recommend assigning that ID the Staff role in Apple Business Manager. There are three classes of roles in Apple Business Manager that define what users of that account can do: Administrator, Manager, and Staff. (There are, in turn, three types of Manager.) Staff roles are limited in scope by design, but one thing they can do is create and renew APNs certificates. 

It makes sense to assign the job of managing APNs certificates to an Apple ID with a Staff role because of the principle of least privilege: An account shouldn’t have any more access than it requires to fulfill its specific responsibilities. So if a Staff role is sufficient to renew APNs certificates but not much else, that’s appropriate for the Managed Apple ID you assign to this specific task. 

Don't Use a Standard Apple ID

Though it might seem tempting, it's a bad idea to create a standard consumer Apple ID for the sole purpose of maintaining your APNs certificates, then share those credentials among your IT staff. In that scenario, anybody in the department who leaves could still gain access to your APNs account even after they are no longer associated with your organization. And this is true even if the Apple ID in question was created on your email domain: anyone with those credentials can still turn on two-factor authentication on a personal device for the account, effectively taking ownership of it. 

How do you know which kind of Apple ID was used to set up your APNs in the first place? One way is to navigate to appleid.apple.com, log in (assuming you have the credentials), and enter the ID there. If you see a screen that looks like this, with an Organization tile, it's a Managed Apple ID:

If you get a screen that looks like this (without that tile), it's not a Managed Apple ID:

Using a Managed Apple ID means your organization always retains control over those credentials. You can, for example, use an account with the Administrator or People Manager role to change the password of that Staff role.

If you did create an APNs certificate with a consumer Apple ID, it’s OK: there’s still a path forward. Set aside some time and contact Apple about changing it to a Managed Apple ID. You cannot effect this change without Apple’s help; only they can make the change in a way that will not require you to re-enroll all of your devices.

There are several ways to create a Managed Apple ID, but only one works for APNs purposes: manual creation. Although federating your identity provider with Apple Business Manager is encouraged in general, federated accounts cannot be used to access Apple’s Push Certificates Portal.

That said, if your organization uses either Azure AD or Google Workspace as your identity provider, turning on federation does have one advantage: It locks your domain and prevents anyone from creating a consumer Apple ID on it. If you don’t have it enabled, anyone who has an email address with your organization’s domain can go to appleid.apple.com and create a consumer Apple ID using your organization’s domain. If you federate, they can’t.

Turning on federation on your domain is not a trivial chore. But it’s a smart thing to do, not least because it ensures the integrity of the Apple IDs you’re using to manage APNs.

What Happens If You Don't Renew in Time

Now, it’s important to keep all this in perspective: If your APNs certificate does expire, it’s not the end of the world—but it is the end, for the time being, of communications between your MDM solution and your devices. Your MDM solution won't be able to send MDM commands to them until you rectify the situation.

If you subsequently renew with the correct credentials—the same Apple ID you used to set up your APNs in the first place—everything will pick back up where it left off; you won’t have to re-enroll those devices.

If you don’t have those original credentials, Apple might be able to set things right, but there’s no guarantee: You must be able to provide the Serial Number and Common Name for the existing APNs certificate in your MDM, along with the name of the Apple ID that you believe was used to create it. Otherwise, the worst will come to pass: You’ll have to enroll all of your devices all over again.

One last thing you should do: document everything. Document the Apple ID and its credentials. Use the Notes field in Apple’s Push Certificates Portal to distinguish certificates if you have more than one. (Be forewarned: This field doesn't support most non-alphanumeric characters.) And most importantly, keep any PEM files securely stored in case you need them when working with Apple to move your APNs certificate to a Managed Apple ID.

One More Thing: Check Your Ports

What if you’ve successfully renewed your APNs certificate, but there still seems to be a communication problem between your devices and your MDM solution? There’s one more thing to check.

APNS uses a few specific ports to communicate with devices. You need to be sure those ports are open and available. As explained in Apple’s support article, APNs relies on TCP port 5223 to communicate with devices. This is an outbound-only connection to Apple’s network; Apple does not require any inbound traffic to be allowed for APNs to work.

If your MDM solution is not cloud-based and has trouble communicating, ask your network administrator to check that support article and the different ports it suggests. (Before you have that conversation, you might want to download a copy of Twocanoes Software’s Push Diagnostics utility, which can verify that the appropriate hosts can be reached on the appropriate ports.) 

As for that customer who reached out about their APNs certificate renewal problems, we were eventually able to untangle it (with some assistance from AppleCare). It was a long solution to a preventable problem.

About Kandji

Kandji makes it simple to keep your APNs certificate up to date, with timely reminders and a crystal clear workflow. With tight integration into the Apple ecosystem, as well as support for things like zero-touch deployment, one-click compliance, and offline remediation, Kandji is a great way to enroll, configure, and secure your devices.