Using alternative Username Formats in Jamf Pro with Okta and Azure AD

Using Jamf Pro, I wanted to to use Okta for authentication, Azure AD as a Directory Data provider, and I wanted the local accounts on the Macs to be the user’s short name or first.last format. You might use different SAML providers for login or a different directory service, but the principles are the same.

But first… what’s in a name? 

In Okta, we always login with a standard Okta username, which normally corresponds to the UPN in Active Directory. In many orgs, that’s the same thing as the user’s email so the users don’t know there’s any distinction. Lots of web sites use that username format, so people are totally used to it by now. But in some orgs there are still lots of systems that still use the shortname (AD’s SAMAccountName/“jdoe” format) or mailNickName (jane.doe format). And users have gotten used to using these formats to log into their Macs and Windows PCs so having a local or mobile account on a Mac that looks like an anything else just seems weird.  

You can tell Okta to feed whatever value you want back to Jamf Pro as the username —It doesn’t have to be the Okta username. If you have your AD feeding user information into Okta, you can send their shortname or mail nickname. Doesn’t matter. Whatever you send is going to appear as the username when an admin logs into Jamf Pro and/or will be used to create the initial account on the Mac when a user logs in when going through Setup Assistant during an automated enrollment flow on a new Mac or when logging in for User Initiated ( Enrollment.  

Oh… and before we get started, I should mention that there’s another way to get the user experience where they login with their short name but the account’s username is actually their long name so you might be better positioned for the future… create your local accounts on the Mac using the user’s full UPN, then add an alias with the shortname… 

sudo dscl . -merge "/Users/${user_name}" RecordName "${short_name}"
diskutil apfs updatePreboot /

That might be easier to implement since you don’t have to deviate from any of the defaults in your IdPs, Directory Services, or Jamf. The way we’re going to discuss in the rest of this post requires some attribute mapping so it’s more work, but it might end up being the cleaner approach.

Here’s the step-by-step… 

1. Add a SAML SSO App in Okta

In the Admin console, navigate to Applications and click “Browse App Catalog”

Search for “Jamf” and pick “Jamf Pro SAML”. 

Add the integration…

Enter your Jamf Pro hostname… 

Your app has now been created and you can now make some additional configurations. First, add some users or groups to the app. I added my MacAdmins group… 

Switch to the “Sign On” tab and click “Edit”.

I want to be able to assign permissions to admins in Jamf Pro based on group membership, so we have to tell Okta to include a list of a user’s groups every time a user signs in. Go down to the group claims section and select “Matches Regex” and “.*” if you want to include every group. But if you only care about a couple groups like one for admins and one for the help desk, then you can set this differently so only the groups you care about get sent over. Jamf Pro uses group membership for other permissions too. You could designate that only members of a Mac Users group have the ability to enroll a device in management, for example. 

If you want the account name in Jamf Pro or on your Macs to be something other than the Okta long username, select it in the “Application username format” dropdown. In the scenario we’re using for this post, you can tell Okta to feed whatever username format you want as long as it works as an account name on the Macs, in Jamf Pro, and we can reliably match it up with something is Azure AD. In the Example that follows, we’ve selected “AD SAM account name”, which is the shortname/jdoe format…

The steps described so far are basically the same as but with more context and screenshots. But do check that official documentation for information about Single Sign out. 

That’s it for setup. The one thing you’ll need to take over to Jamf Pro is Okta’s SAML metadata. Go down to the SAML Singing Certs section near the bottom of the Sign On tab and select “View IdP metadata” from the Actions drop down. 

You can save that xml to a file on your computer and then upload that file to Jamf Pro, or you can just grab the URL and tell Jamf Pro to grab the data from there…

The result of all this will be that when a user logs into Jamf Pro via Okta (whether to the admin console, when enrolling a device, or in Self Service), Okta is going to send Jamf Pro a set of SAML assertions about the user and Jamf Pro will use that to figure out what the user can do. 

The way we have it set up, the SAML assertions will include the NameID and a list of the user’s group memberships.  

Step 2: Configure SAML/SSO in Jamf Pro

Switch over to Jamf Pro and create the SSO settings. has the official docs on how to do it. In the screenshot below you can see that I uploaded a metadata file but it’s easier to just paste in the URL. 

There are a couple options available that the docs don’t go into too much. The Identity Provider User mapping tells Jamf Pro what attribute to pull out of the SAML assertions to indicate the user that’s logging in. The Jamf Pro User mapping tells Jamf Pro what field to look in when it’s trying to match that information to a user it knows about. Most people don’t do anything fancy but it’s super flexible. 

Step 3: Configure Jamf Pro for Admin Logins

There are a couple options here. If you just have a couple of full admins that are ever going to sign into Jamf Pro, you can just create some local accounts for them. Select Create Standard Account for the account type…   

The name format you put in here depends on the format you used for the Name ID format on the Okta side and how you did the mappings. If you used short name (AD SAM Account Name) and in the Jamf Pro SSO settings you said to match the NameID attribute from the SAML assertions to the UserName field in Jamf Pro, you’d put “jdoe” in as the admin account’s username… 

It doesn’t really matter what format you use. The admin is still going to log into Okta with their Okta username no matter what. The “jdoe” short name is just what’s going to appear in things on the Jamf Pro side like change management logs, etc. If you’re matching on Username, Full Name and Email Address are optional. 

Step 4: Setting up for User and Group Data Lookups

We’re using Okta for authentication but our “source of truth” for directory (users and groups) data is Azure AD. When we assign devices to a user and want to get their information (phone number, department, etc.) or figure out what groups they’re in for scoping apps/policies/profiles/etc, it’s the Azure data we want to look at.

In Jamf Pro, go into Settings > Cloud Identity Providers and click the “+” to add a connection. 

In our case we’re using Azure AD…

When you click “Next” you’ll need to authenticate into Azure AD as an admin with permissions to create app integrations. Once that’s done there are some settings to enter. These are a lot like what we did when mapping SAML IdP fields to their counterparts in Jamf Pro. 

All the groups I use are just lists of users, not lists of sub-groups, so I didn’t have to turn on transitive groups. That makes for way faster lookups, but if you’re in a big organization you’ll probably have lots of complex groups so you’ll probably need to turn it on. 

On the mappings tab, if you use the default mappings, you’ll see that Jamf’s user name is paired up with Azure’s UPN. 

That’s clearly Azure’s go-to as far as the essential unique user identifier, but if you need to stick with shortname, that’s supported as of Jamf Pro 10.37. Change the mapping for Jamf’s User Name field to “onPremisesSamAccountName”. Make the same change to your user id mapping for the Group membership lookup section (further down the page) as well. 

Different orgs have different custom extensions and fields in their directories. That onPremisesSamAccountName attribute we mentioned is typical when we’re using MS’s default AD sync tool, but the ID field you want to use could be something different. For example, if you want to use jane.doe instead of jdoe or, you might find that format in mailNickname. You can look up data yourself via graph API to see how your org has things set up.$select= userPrincipalName,displayName,givenName,mail,identities,surname,employeeId,mailNickname,onPremisesSamAccountName,preferredName

    "userPrincipalName": "",
    "displayName": “Jane Doe",
    "givenName": "Jane",
    "mail": "",
    "surname": "Doe",
    "employeeId": null,
    "mailNickname": "jane.doe",
    "onPremisesSamAccountName": "jdoe",
    "preferredName": ""

Just make sure that whatever attribute you choose is going to match up 1:1 with whatever format you’re feeding as the nameID in your Okta app setup. 

Step 5: Setting up for Device Enrollment

If you want your users to have local Mac accounts named after their shortname, enter the variable where you have that saved. In the example we’ve been showing here, that’s Jamf’s User Name field but you can use any of these variables. 

  • $EMAIL
  • $PHONE
  • $ROOM

Since we want the user’s short name to be their account name and we have that mapped into Jamf Pro’s User Name field, we’ll set the prestage up like this…


Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this: