Edit

Share via

Enable Kerberos SSO to on-premises Active Directory and Microsoft Entra ID Kerberos resources in Platform SSO

Mac users can join their new device to Microsoft Entra ID during the first-run out-of-box experience (OOBE). The macOS Platform single sign-on (PSSO) is a capability on macOS that is enabled using the Microsoft Enterprise Single Sign-on Extension. PSSO allows users to sign in to a Mac device using a hardware-bound key, smart card, or their Microsoft Entra ID password.

This tutorial shows you how to configure Platform SSO to support Kerberos-based SSO to on-premises and cloud resources, in addition to SSO to Microsoft Entra ID. Kerberos SSO is an optional capability within Platform SSO, but it's recommended if users still need to access on-premises Active Directory resources that use Kerberos for authentication.

Prerequisites

Set up your macOS device

Refer to the Microsoft Entra ID macOS Platform SSO documentation to configure and deploy Platform SSO. Platform SSO should be deployed on Enterprise-managed Macs regardless of whether you choose to deploy Kerberos SSO using this guide.

Kerberos SSO MDM profile configuration for on-premises Active Directory

You should configure separate Kerberos SSO MDM profiles if you plan to use both Microsoft Entra ID Cloud Kerberos and on-premises Active Directory realms. It's recommended to deploy on-premises Active Directory profile before the Microsoft Entra ID Cloud Kerberos profile.

Use the following settings to configure the on-premises Active Directory profile, ensuring that you replace all references to contoso.com and Contoso with the proper values for your environment:

Configuration Key Recommended Value Note
Hosts <string>.contoso.com</string> Replace contoso.com with your on-premises domain/forest name
Hosts <string>contoso.com</string> Replace contoso.com with your on-premises domain/forest name. Keep the preceding . characters before your domain/forest name
Realm <string>CONTOSO.COM</string> Replace CONTOSO.COM with your on-premises realm name. The value should be all capitalized.
PayloadOrganization <string>Contoso</string> Replace Contoso with the name of your organization 
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>PayloadContent</key>
    <array>
        <dict>
            <key>ExtensionData</key>
            <dict>
                <key>allowPasswordChange</key>
                <true/>
                <key>allowPlatformSSOAuthFallback</key>
                <true/>
                <key>performKerberosOnly</key>
                <true/>
                <key>pwReqComplexity</key>
                <true/>
                <key>syncLocalPassword</key>
                <false/>
                <key>usePlatformSSOTGT</key>
                <true/>
            </dict>
            <key>ExtensionIdentifier</key>
            <string>com.apple.AppSSOKerberos.KerberosExtension</string>
            <key>Hosts</key>
            <array>
                <string>.contoso.com</string>
                <string>contoso.com</string>
            </array>
            <key>Realm</key>
            <string>CONTOSO.COM</string>
            <key>PayloadDisplayName</key>
            <string>Single Sign-On Extensions Payload for On-Premises</string>
            <key>PayloadType</key>
            <string>com.apple.extensiblesso</string>
            <key>PayloadUUID</key>
            <string>1aaaaaa1-2bb2-3cc3-4dd4-5eeeeeeeeee5</string>
            <key>TeamIdentifier</key>
            <string>apple</string>
            <key>Type</key>
            <string>Credential</string>
        </dict>
    </array>
    <key>PayloadDescription</key>
    <string></string>
    <key>PayloadDisplayName</key>
    <string>Kerberos SSO Extension for macOS for On-Premises</string>
    <key>PayloadEnabled</key>
    <true/>
    <key>PayloadIdentifier</key>
    <string>2bbbbbb2-3cc3-4dd4-5ee5-6ffffffffff6</string>
    <key>PayloadOrganization</key>
    <string>Contoso</string>
    <key>PayloadRemovalDisallowed</key>
    <true/>
    <key>PayloadScope</key>
    <string>System</string>
    <key>PayloadType</key>
    <string>Configuration</string>
    <key>PayloadUUID</key>
    <string>2bbbbbb2-3cc3-4dd4-5ee5-6ffffffffff6</string>
    <key>PayloadVersion</key>
    <integer>1</integer>
</dict>
</plist>

Save the configuration using a text editor with the mobileconfig file extension (for example, the file could be named on-prem-kerberos.mobileconfig) after updating the configuration with the proper values for your environment.

Kerberos SSO MDM profile configuration for Microsoft Entra ID Cloud Kerberos

You should configure separate Kerberos SSO MDM profiles if you plan to use both Microsoft Entra ID Cloud Kerberos and on-premises Active Directory realms. It's recommended to deploy on-premises Active Directory profile before the Microsoft Entra ID Cloud Kerberos profile.

Use the following settings to configure the Microsoft Entra ID Cloud Kerberos profile, ensuring that you replace all references with the proper values for your tenant:

Configuration Key Recommended Value Note
preferredKDCs <string>kkdcp://login.microsoftonline.com/aaaabbbb-0000-cccc-1111-dddd2222eeee/kerberos</string> Replace the aaaabbbb-0000-cccc-1111-dddd2222eeee value with the Tenant ID of your tenant, which can be found on the Overview page of the Microsoft Entra Admin Center
PayloadOrganization <string>Contoso</string> Replace Contoso with the name of your organization 
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>PayloadContent</key>
    <array>
        <dict>
            <key>ExtensionData</key>
            <dict>
                <key>usePlatformSSOTGT</key>
                <true/>
                <key>performKerberosOnly</key>
                <true/>
                <key>preferredKDCs</key>                         
                <array>
                <string>kkdcp://login.microsoftonline.com/aaaabbbb-0000-cccc-1111-dddd2222eeee/kerberos</string>
                </array>
            </dict>
            <key>ExtensionIdentifier</key>
            <string>com.apple.AppSSOKerberos.KerberosExtension</string>
            <key>Hosts</key>
            <array>
                <string>windows.net</string>
                <string>.windows.net</string>
            </array>
            <key>Realm</key>
            <string>KERBEROS.MICROSOFTONLINE.COM</string>
            <key>PayloadDisplayName</key>
            <string>Single Sign-On Extensions Payload for Microsoft Entra ID Cloud Kerberos</string>
            <key>PayloadType</key>
            <string>com.apple.extensiblesso</string>
            <key>PayloadUUID</key>
            <string>00aa00aa-bb11-cc22-dd33-44ee44ee44ee</string>
            <key>TeamIdentifier</key>
            <string>apple</string>
            <key>Type</key>
            <string>Credential</string>
        </dict>
    </array>
    <key>PayloadDescription</key>
    <string></string>
    <key>PayloadDisplayName</key>
    <string>Kerberos SSO Extension for macOS for Microsoft Entra ID Cloud Kerberos</string>
    <key>PayloadEnabled</key>
    <true/>
    <key>PayloadIdentifier</key>
    <string>11bb11bb-cc22-dd33-ee44-55ff55ff55ff</string>
    <key>PayloadOrganization</key>
    <string>Contoso</string>
    <key>PayloadRemovalDisallowed</key>
    <true/>
    <key>PayloadScope</key>
    <string>System</string>
    <key>PayloadType</key>
    <string>Configuration</string>
    <key>PayloadUUID</key>
    <string>11bb11bb-cc22-dd33-ee44-55ff55ff55ff</string>
    <key>PayloadVersion</key>
    <integer>1</integer>
</dict>
</plist>

Save the configuration using a text editor with the mobileconfig file extension (for example, the file could be named cloud-kerberos.mobileconfig) after updating the configuration with the proper values for your environment.

Note

Make sure you pay attention to the usePlatformSSOTGT and performKerberosOnly keys. If usePlatformSSOTGT is set to true, the Kerberos Extension uses the TGT from Platform SSO with the same realm. The default is false. If performKerberosOnly is set to true, the Kerberos extension doesn't perform password expiration checks, external password change checks, or retrieve the user’s home directory. The default is false. This is applicable to both the on-premises and cloud configurations, these keys should be configured in both profiles.

Intune configuration steps

If you use Intune as your MDM, you can perform the following steps to deploy the profile. Make sure you follow the [previous instructions](#Kerberos SSO MDM profile configuration for on-premises Active Directory) about replacing contoso.com values with the proper values for your organization.

  1. Sign in to the Microsoft Intune admin center.
  2. Select Devices > Configuration > Create > New policy.
  3. Enter the following properties:
    • Platform: Select macOS.
    • Profile type: Select Templates.
  4. Choose the Custom template and select Create.
  5. In Basics, enter the following properties:
    • Name: Enter a descriptive name for the policy. Name your policies so you can easily identify them later. For example, name the policy macOS - Platform SSO Kerberos.
    • Description: Enter a description for the policy. This setting is optional, but recommended.
  6. Select Next.
  7. Enter a name in the Custom configuration profile name box.
  8. Choose a Deployment channel. Device channel is recommended.
  9. Click the folder icon to upload your Configuration profile file. Choose the kerberos.mobileconfig file you [saved previously](#Kerberos SSO MDM profile configuration for on-premises Active Directory) after customizing the template.
  10. Select Next.
  11. In Scope tags (optional), assign a tag to filter the profile to specific IT groups, such as US-NC IT Team or JohnGlenn_ITDepartment. Select Next.
  12. In Assignments, select the users or user groups that will receive your profile. Platform SSO policies are user-based policies. Don't assign the platform SSO policy to devices.
  13. Select Next.
  14. In Review + create, review your settings. When you select Create, your changes are saved, and the profile is assigned. The policy is also shown in the profiles list.
  15. Repeat this process if you need to deploy both profiles because you will use both on-premises Kerberos SSO and Microsoft Entra ID Cloud Kerberos.

The next time the device checks for configuration updates, the settings you configured are applied.

Testing Kerberos SSO

Once the user has completed Platform SSO registration, you can check that the device has Kerberos tickets by running the app-sso platform -s command in the Terminal app:

app-sso platform -s

You should have two Kerberos tickets, one for your on-premises AD with the ticketKeyPath value of tgt_ad and one for your Microsoft Entra ID tenant with the ticketKeyPath value of tgt_cloud. The output should resemble the following:

Screenshot of the output of app-sso platform -s in the macOS Terminal app.

Validate your configuration is working by testing with appropriate Kerberos-capable resources:

  • Test on-premises Active Directory functionality by accessing an on-premises AD-integrated file server using Finder or a web application using Safari. The user should be able to access the file share without being challenged for interactive credentials.
  • Test Microsoft Entra ID Kerberos functionality by accessing an Azure Files share enabled for Microsoft Entra ID cloud kerberos. The user should be able to access the file share without being challenged for interactive credentials. Refer to this guide if you need to configure a cloud file share in Azure Files.

Note

Note that Microsoft's Platform SSO implementation is responsible for issuing the Kerberos TGTs and delivering them to macOS so that macOS can import them. If you see TGTs when running app-sso platform -s, then the TGTs have been successfully imported. If you experience any ongoing Kerberos issues, such as issues accessing on-premises resources via Kerberos, then it's recommended to reach out to Apple for support with further configuration of your Kerberos MDM profiles. The Kerberos implementation in macOS uses native Apple-provided Kerberos capabilities.

Known Issues

Kerberos SSO extension menu extra

When deploying support for Kerberos SSO with Platform SSO, the standard Kerberos SSO extension capabilities of macOS are still used. Like with a deployment of the native Kerberos SSO extension without Platform SSO, the Kerberos SSO extension menu extra will appear in the macOS menu bar:

Screenshot of the macOS Kerberos SSO extension menu extra.

When deploying Kerberos support with Platform SSO, users don't need to interact with the Kerberos SSO extension menu extra to have Kerberos functionality work. Kerberos SSO functionality will still operate if the user doesn't sign into the menu bar extra and the menu bar extra reports "Not signed in". You may instruct users to ignore the menu bar extra when deploying with Platform SSO, per this article. Instead, make sure that you validate that kerberos functionality works as expected without interaction with the menu bar extra, as outlined in the Testing Kerberos SSO section of this article.

Browser Support for Kerberos SSO

Some browsers require additional configuration to enable Kerberos SSO support, including if you are using Platform SSO to enable Kerberos on your macOS devices. When deploying Kerberos support on macOS, deploy the appropriate settings for each of the browsers you utilize to ensure they can interact with the macOS Kerberos SSO features:

  • Safari: supports Kerberos SSO by default
  • Microsoft Edge:
    • Configure the AuthNegotiateDelegateAllowlist setting to include your on-premises Active Directory forest information: AuthNegotiateDelegateAllowlist
    • Configure the AuthServerAllowlist setting to include your on-premises Active Directory forest information: AuthServerAllowlist
  • Google Chrome
    • Configure the AuthNegotiateDelegateAllowlist setting to include your on-premises Active Directory forest information: AuthNegotiateDelegateAllowlist
    • Configure the AuthServerAllowlist setting to include your on-premises Active Directory forest information: AuthServerAllowlist
  • Mozilla Firefox
    • Configure the Mozilla Firefox network.negotiate-auth.trusted-uris and network.automatic-ntlm-auth.trusted-uris settings to enable Kerberos SSO support

See also