Demystifying Kerberos Single Sign-On for iOS

Hello everyone,

Well a few articles in and people still think I’m not 100% stupid. As we say in Boston, that is wicked pissah. I want to take a moment or two to editorialize what it’s like to be a mobile systems engineer in the enterprise world. We are MORE stuck with stigmas that almost any position. People just think we’re administrators and not as talented as other infrastructure architects or engineers. I think that’s perfectly okay! I got my job at BlackBerry working next to people that were principal’s at Microsoft for 10 years so I’m used to an uphill battle.

So now I have setup what I wanted to blog about today….an aspect of “identity management.” Yes I know that is becoming the most ridiculous word ever lately. So many things are being lumped into those two words. So let’s rewind three years ago, Apple thought about how could they actually make their product enterprise grade. Then almost like the “Brilliant!” guys from that beer commercial some time back, they decided let’s give people Single Sign-On, but let’s “NOT” really tell them how to do it, make it work, or make it even remotely easy to accomplish it.

WTF is Kerberos?

I try not to make any assumptions. So people ask what “exactly” is kerberos? This is kerberos!


Technically, I’m right that is Kerberos of greek mythology from the kids movie Hercules. I also remember Kerberos quite well from my World of Warcraft and Final Fantasy days, but obviously you don’t want to hear about 40-man raids in a top raiding guild. Okay…moving on!

Kerberos is a network authentication protocol developed and maintained by MIT since the 80s. The image below is one of my favorite images. For our purposes, to keep it really simple since this isn’t a class on Kerberos, we use kerberos with certificate-based authentication on iOS to authenticate seamlessly to applications.  The useful thing about Kerberos with CBA (Certificate-Based Authentication) is that you are able to use it without being domain-joined to achieve Single Sign-On in a seamless way if you build your environment correctly


What are the requirements in iOS?

A major part of the reason I decided to write this article is that the information out there is VERY inconsistent. I know everyone hates BlackBerry and blah blah, but don’t you wish your MDM vendor was even in the same ballpark on documentation? I know that I do.

So, for requirements it’s straight forward:

  • Either publically or over VPN, you must publish SRV records with your servers running a KDC aka _kerberos._tcp
  • You need to build a properly-configured Single Sign-On Payload (sounds much easier than it actually is, we’ll cover that later)
  • Deliver the KDC service certificate to the device
  • Allow the device to reach your KDC servers over Port 88
  • Deliver certificates that meet the Kerberos requirements (which we’ll also cover later)

It’s very possible that I’m missing a few things that people will nerd/kerberos rage on me later, but these have been the key items that I have to make sure I catch on my implementations. I hope for your sake that you have a SSO product that has a cloud KDC to simplify many of these steps, such as VMWare Identity Manager

iOS Single Sign-On Payload

I know you think this is just I’ll write this and that and it will be easy in 10 lines of code (or JSON for that matter). So before you do anything, you need to analyze how your AD structure is. This is what I mean, the two things that really matter to you is your sAMAccountName and your UPN (User Principal Name). Sure most companies will be JTowles is my username and is my UPN. Now in the O365 world, the best practice is SMTP=UPN which is why  I said it like that.

The problem you COULD run into is if you do something different with your username like TowlesJ, which will break your attempts all together. Let me explain how it works, then I’ll cover it more in certificate requirements. Your email address up to the @ sign must match your username aka Kerberos Principal Name. Failure to do so, will cause Kerberos Authentication to fail. Simply, you will need to engineer around the issue, which you can do in some MDM’s which I will cover in a moment. Essentially, when the authentication happens, it will require that your Kerberos Principal Name in the payload correlate to an entry in one of two fields of the certificate it presents to your KDC. Most times, you will be leveraging some form of Kerberos Constrained Delegation to get Kerberos tickets and have a seamless flow.

Likely the issue you are asking yourself is, will I need to manually create this flow for every single user if my username doesn’t match? The answer is no! Depending on your MDM, it will hopefully be able to leverage lookup values, which you can likely work with RegEx expressions to achieve. For example, perhaps you use a Regex express to take your email address and strip out the @ and domain to make your email address and kerberos principal name match.  This screenshot below shows how you would accomplish exactly that. The typical best practice is to pass the username into the Kerberos Principal name field, but in some circumstances we must be engineers

Screen Shot 2017-09-09 at 6.30.37 PM.png

So that’s the first part of your Kerberos SSO Profile. The other key parts are:

  • Realm (which is your realm in ALL CAPS, typically the domain) aka EXAMPLE.COM
  • You tie the renewal certificate to another component of your payload like your SCEP profile or however your MDM is accomplishing certificate automation.
  • URL Prefixes for Kerberos Authentication (this is whatever KDC endpoints you are hitting) which is typically either a cloud Kerberos endpoint or some authentication layer in your environment
  • Whitelisted App IDs: I strongly recommend this list below on top of anything else you want to allow:
    • (iOS Safari, because duh!)
    • (this is for apps that open a Safari window inside of their application)
    • Whatever Apps you are enabling for SSO

Don’t forget to add in the KDC certificates so that you can actually authenticate. It turns out that Kerberos likes security.

Certificate Requirements

I found the certificate stuff to be the hardest part of making this actually work. Part of the problem is that vendors (whether its Apple being distant or your MDM) they all feel like its not their job to help make it work end-to-end. I suggest before getting started to install the Enterprise SSO Apple Profile to help with debugging via xCode.

So, its two parts really first what you need to do on the CA and then what you need to do on the MDM side.

On the CA side, these are the requirements:

  • Grant the OID (Kerberos Client Authentication) to the Template
  • Grant the OID (Client Authentication) to the Template
  • Make sure your service account has access to read/enroll the certificate along with giving authenticated users read only access or your generations will fail.

On the MDM side, these are the requirements:

  • Create the Subject Name with your NTID
  • Create SANs for the following:
    • UPN with the user’s UPN as the value
    • Email with the user’s email as the value
    • Optionally create a DNS field for UID if you are doing device compliance (i.e. DNS Name UID=(Whatever the UID of the device is)
  • Make sure the certificate can be used for signing and encryption
  • Make sure the template you provide on the iOS side matches the template name (NOT THE TEMPLATE DISPLAY NAME) from your CA

Like I said earlier, make sure that the content before the @ sign on one of your SANs matches the Kerberos principal name in the profile. Failure to do this will result in authentication failures. I also strongly suggest to keep this separate from your WiFi or VPN payloads as you may have to update it frequently to add new applications or tweak it.

Final Thoughts

I will say from experience that this can be a very frustrating chore getting actual seamless Mobile SSO working, but it is so rewarding once you are successful. You should definitely make sure that you setup proper step-up/step-down methods in your SSO posture. Failure to do so could create a major issue for your users. It’s one thing, to have to put in your username and password but an entirely different situation to not be able to access a critical application. As an engineer, you always need to plan for the worst case scenario and have a break glass policy. I hope this helps people as I know these issues were not without their pain points for me.

16 thoughts on “Demystifying Kerberos Single Sign-On for iOS”

  1. This has been a great resource but unfortunately I have not been to get SSO to work in my environment . I quickly tried in the VMTestDrive sandboxes of IDM & UEM and was successful.

    I believe that my problem is with the on-prem KDC not quite right.
    I have port 88 open and the SRV records set but I keep getting this error:
    _gss_mg_error: captured unable to reach any KDC in realm MONCTON.CA, tried 2 KDCs (-1765328228) from underlaying mech kerberos 5

    Is there a way to disable on-prem KDC and use CLOUD?
    I have also had to deal with SAM & UPN not being the same.

    This is a very detailed article you put together. Would you be chance have any suggestions on what may be keeping our mobile SSO auth from working. We are using AirWatch v1811 with VIDM on-premise connected to Cloud KDC. Our users samaccount doesn’t match our UPN in AD. So when our users enroll in Airwatch their username lookup value is short login ID not email formatted value that we have set for UPN.

    When using lookup value in AirWatch some will cause profile install failure stating incorrect value used for “PrincipleName”. Breakdown of the error reported by IOS.

    Error Code 1000 The profile “iOS Mobile SSO/V_12” is invalid.
    Error Code 2000 The payload “iOS Mobile SSO/V_12” is invalid.
    Error Code 2004 The field “PrincipalName” contains an invalid value.
    Profile iOS Mobile SSO

    1. Hi Brandon,

      So you need your certificate to have a SAN as NT Principal Name that matches the principal name of your Kerberos Profile.

      So your Kerberos Profile will ALWAYS have your NTID aka samAccountName. The certificate basically needs the NT Principal Name field to match that. So if you are using DCOM you can add a SAN that matches that. I believe you can either just do a SAN attribute that matches it called NT Principal Name or an email address starting with the NT Principal Name (e.g)

      Your kerberos profile should have Kerberos Principal Name as {EnrollmentUser} , Realm as VMWAREIDENTITY.COM , and Renewal Certificate as your CA or the AW SCEP certificate.

      So if my KRB Prin is jjtowles then I should have an entry in the SAN called jjtowles also. If you can’t achieve that, let me know.

  3. Great article, Thanks for the info.
    We have Jamf as our iOS MDM and SSO is the key to user acceptance (Lots of internal hosted sites through per app which is a pain).
    Going to give this a spin later. wish me luck!

  4. We face this issue in internal network. We have Cisco ISE and CDA which ensures that we have the same vlan, no matter if WiFi or lan. Btw as realm we have AD domain name, which is UPN as well and is not routable.

    1. I wonder if it has anything to do with the DNS records at all. Did you try to hit a specific node instead of the load balancer to rule things out? I would honest try to nail down the individual timing of each action. Internal KDC is really a few settings: DNS, the KDC servers you specify in the run-time Config and the cert itself. That’s outside of the stuff like OCSP etc.

      I’d honestly try to build a test environment with the cloud KDC and see if it’s faster. I prefer cloud KDC personally

  5. One other thing I thought of, have you checked the public DNS entries to make sure you aren’t having issues there? If I was you I’d probably install the iOS Kerberos debugging profile to see if it tells you more. PCAPs on the iOS device might help also to see where the latency is getting created

  6. Very interesting article! I came to your blog looking for a solution to a certain case. We have airwatch and we use iOS mobile SSO. Authentication goes to ADFS 3.0 which federates different apps. During the first login for some days of inactivity login to such app from iOS can take up to 30-40s. No issues when we do not use iOS mobile SSO. Any thoughts, did you saw something similar?

      1. Adfs doesn’t matter at all for this. Essentially what Kerberos for mobile SSO is doing is authenticating against the default policy for VIDM. In this circumstance, I would suggest using VIDM as the identity provider. The biggest issues with authentication happen because VIDM nodes aren’t very good at authentication. I suggest using the VIDM connectors as your authenticators preferably as VMWare ESCs. I’ve found in private clouds that VIDM connectors will auth about 5 times faster than individual nodes. I would also suggest using a hybrid KDC deployment over internal KDC for VIDM. The reason is that you don’t want to open traffic up to TCP/88 from external devices when something is already in place.
        What I tend to find in a lot of environments is that port 88 is blocked on most wireless networks so you might be running into a few challenges there. The optimal architecture for running VIDM is a cluster in the DMZ and your connectors over ESCs internally handling certs, radius, and Kerberos.

        It’s a stronger security posture and eliminates some of the challenges

      2. Just to follow up, it’s not an ADFS issue at all, it tends to be an end to end issue. I would definitely be using VIDM as my default IDP and then use ADFS for the apps themselves. Kerberos of course is handled on the nodes for Mobile SSO for iOS vs desktop Kerberos on the connectors

Leave a Reply

Scroll to Top
%d bloggers like this: