Configure macOS for PennKey Authentication

PennKey logins allow any previously-allowed user within SAS, or the university, the ability to access a public computer without having a local user account on that computer or a domain user account. All Macs in the SAS Central Pool Classrooms use this type of authentication.

Mac OS X uses PennGroups and kerberos to facilitate PennKey authentication. The following procedure works on OS X versions 10.8.4 – 10.14.6

Requirements: access to PennNet, PennGroups LDAP account (ask jasonrw), administrative access to the target Mac OS X 10.8.4 – 10.14.6

UPDATE (1/31/21): Apple introduced lots of changes with macOS 10.15 “Catalina.” Some of these differences broke the manner in which we have traditionally configured PennKey authentication. The good news is that 10.13, 10.14 Macs, configured for PennKey authentication and upgraded to 10.15 continue to permit PennKey logins. The Bigfix fixlet, which configures PennKey authentication no longer works.

The same can be said for macOS 11 (10.16?) “Big Sur.” Upgraded PennKey Macs do continue to permit PennKey logins. The rub is that none of the configuration profiles installed onto macOS are accessible by PennKey users. Admin users are fine, but unprivileged PennKey users will get a barrage of admin authentication prompts which never end. Even if an admin username/password are provided, the prompts keep coming. At this point, Big Sur is not viable for use with PennKey authentication.

UPDATE (2/15/18): The EMS team has created an IEM (BigFix) fixlet which will do all of the following on any relevant Mac. As much fun as it has been going through motions of setting up this type of access manually, it is no longer required.

Note: This process modifies how OS X authenticates users each time they log in. Mistakes here could render the Mac unable to authenticate any user. It would not be a bad idea to make a backup of the target Mac prior to beginning this configuration procedure. I use Disk Utility for this purpose.

The first part of this involves modifying three configuration files that help set up kerberos authentication.

The FIRST part is to create a “krb5.conf” file on the target system, or download one from here or open up the terminal and create a new file, called krb5.conf, under /etc (sudo nano /etc/krb5.conf). Edit the file to match what is listed below.

The completed krb5.conf file

The completed krb5.conf file

The SECOND part is to setup the Mac OS X login window for kerberos authentication by modifying the preexisting “/etc/pam.d/authorization” file.

Again, from the Terminal and type sudo nano /etc/pam.d/authorization. Then, navigate to the first auth optional section and add the value“default_principal” to the end of the line, as shown below.

The /etc/pam.d/authorization file after modification.

The /etc/pam.d/authorization file after modification.

THIRD. Configure Open LDAP to ignore certificates by editing the preexisting “/etc/openldap/ldap.conf” file. From the Terminal, enter the command sudo nano /etc/openldap/ldap.conf. You will need to edit the line that reads TLS_REQCERT DEMAND and change DEMAND to never as shown below.

The modified ldap.conf file. Note the "never" change.

The modified ldap.conf file. Note the “never” change.


FOURTH, configure Directory Access. This is by far the most tricky part of the whole procedure. Steps have to be performed exactly as indicated or else PennKey authentication WILL NOT work.

Open the Directory utility, while logged-in as an admin user. Apple buries the Directory Utility in the Users applet in System Preferences.

Select LDAPv3 and then click the edit box below and a new window will appear. Click on New then click Manual then click Edit. Under the Connections tab, enter the information as shown in the box below.

  1. name the configuration PennGroups
  2. enter the server name
  3. check the box Encrypt using SSL
The custom PennGroups configuration in the Directory Utility.

The custom PennGroups configuration in the Directory Utility.


The PennGroups account settings.

The PennGroups account settings.

Leave the rest at their defaults and then click on Search and Mappings tab at the top.

  1. In the drop down box next to Access this LDAPv3 server… select Custom
  2. Select the Default Attribute Types, then click Add, then select Record Types and highlight Users
  3. Select the Users record type you just added and click the Add button that is located under the right pane (Map to ‘any’ items in list)
  4. Add the value pennidTranslation and
  5. Set the Search base for the Users record type: ou=pennnames,dc=upenn,dc=edu and select Search in all subtrees as shown below.
The Search & Mappings settings.

The Search & Mappings settings.

Now comes the fun part, adding the attributes for the Users record type. They all have to be added and in the following order. The order must be correct and exact, or else none of this will work.

  1. AuthenticationAuthority
  2. NFSHomeDirectory
  3. PrimaryGroupID
  4. RealName
  5. RecordName
  6. UniqueID
  7. UserShell
Each one of these attributes has a certain value attached to it. The value is entered in the right-hand box, next to the attribute. The first is AuthenticationAuthority.
  1. AuthenticationAuthority = pennname
  2. NFSHomeDirectory = #/Users/$pennname$
  3. PrimaryGroupID = #20
  4. RealName = cn
  5. RecordName = pennname
  6. UniqueID = pennid
  7. UserShell = #/bin/bash
An example of one of the attribute settings that must be completed successfully.

An example of one of the attribute settings that must be completed successfully.

Almost done! Next, we have to configure directory authentication for the whole configuration. ISC would have had to provide the organization with a username and password for this part. Open the “Security” tab next to the “Search and Mappings” tab.

  1. Check the box to Use authentication when connecting
  2. Enter the Distinguished Name of the principal (service account) that has been setup (see the prerequisites) in the format uid=<principal>,ou=entities,dc=upenn,dc=edu
    for example:
  3. And enter the password for that account, as shown below. OK out of the PennGroups settings dialogs until you are back at the Directory Utility window.
Enter the UID for your organization with the password.

The security tab

OS X has to be told to check the directory each time a username and password is entered. Click on Search Policy at the top. Make sure you have selected the Authentication button and for the Search option, select Custom Path and then click the Plus (+) to add the LDAP directory, which should be available for you to select as shown below. Click Apply, and you are now finished!


The authentication path lists local account, then directory accounts are checked at log on.

The authentication path lists local account, then directory accounts are checked at log on.

Change the log on window for OS X to not show a list of users, but just the username and password dialog boxes, or else you will not be able to log on with a PennKey. Go into System Preferences \ Users & Groups \ Select the “Login Options” button and select “Name and password” radio button under the “Display login windows as:” section.

The Login Options under the Users & Groups applet.

The Login Options under the Users & Groups applet.

REBOOT and test a PennKey log on. There may be a red dot in the user name field stating network accounts are not available from the log on screen. That *should* go away with a few seconds after the Mac boots. If it does not, check the network connection to PennNet and try again.


I would also add a message to the login screen indicating that PennKey logins are supported in addition to local logins, and that domain logins may or may not be supported. Running the following command from the terminal or from an ARD Unix command will make such a change.

sudo defaults write /Library/Preferences/ LoginwindowText "Please log in with your PennKey username and password."

Jason Watkins