Configure the Passport Library Item

By Ryan Cleary

Learn how to configure and deploy the Passport Library Item

Note: Microsoft Entra ID is the new name for Azure AD (Azure Active Directory)

Please look at our Passport Compatibility article for more information about how Passport interacts with other Kandji and macOS features.

Add a Passport Library Item

  1. In the left navigation bar, navigate to Library.
  2. In the upper right corner, click Add New.
  3. Scroll to Enrollment Configurations and select Passport.
  4. Click Add & Configure.
    nPhaKGELGdxca3pwikkhnQCmOfptvEpfOg

  5. Add a descriptive title.
  6. Click Select Blueprint and assign one or more Blueprints that will use this Library Item.
    rMcL9eaMqa0zxJyNcbw0QTr8iIav9ez8AQ

  7. Configure the Authentication configuration, User provisioning, Access, Login window, and Help window sections to fit your environment. (For details, see below.)
  8. Click Save.

Authentication Configuration

The way you configure authentication for the Passport Library Item depends on which IdP you're using.

Configure Secure LDAP for Google Workspace

For Google Workspace, provide the certificate that you downloaded from Google Workspace. See our Passport Configuration with Google Workspace Support article for more information. 

  1. In the Settings section, in the Authentication configuration section, click Identity provider and select Google Workspace.

  2. In the Upload certificate from Google Workspace field, click the link to upload the certificate you downloaded from Google.

  3. In the Choose Files to Upload window, navigate to the folder that contains your compressed certificate file and select the compressed certificate file.
  4. Click Upload.
  5. If you see the Validating file message, wait a few moments for the validation to complete.
  6. Confirm that the compressed certificate file is displayed.

Continue with the User Provisioning section of this article.

Configure OpenID Connect (OIDC)

For Microsoft Entra ID, Okta, OneLogin, or another IdP that uses OpenID Connect (OIDC), you can configure Passport to use one of the following authentication modes:

  • Mac Login: Presents username and password fields to the user.
  • Web Login: Presents a web view of your IdP's login fields, to support users by providing an additional factor of authentication; additionally, it displays a Local Login button. If you set your Identity provider to be OneLogin or Other, you must configure an additional app, as outlined later in this article.

In Web Login authentication mode, if users click the Local Login button, Passport removes the web view window and displays username and password fields and a Web Login button so users can return to the Web Login mode.

If the Passport Authentication mode is set to Web Login, which supports multi-factor authentication (MFA), users will need to authenticate again. If FileVault is set to Disallow automatic FileVault Login and the Passport Authentication mode is set to Web Login, users will need to authenticate three times in total after a device has been powered on or after a device restart.
You will not be able to save the Passport Library Item without entering values in both the Identity provider URL and Client ID (Password Sync) fields.
  1. In the Settings section, in the Authentication configuration section, click Identity provider and select your IdP.
    V0yYXqUtYQ19ysJonw13ayFVuYBmdLeyCg

  2. Enter the appropriate values in the Identity provider URL and Client ID (Password Sync) fields.

    Be sure your OpenID Connect (OIDC) application is configured with your compatible identity provider (IdP). You will need your identity provider URL and the OIDC application ID to configure Passport. For more information on how to configure specific identity providers, see our Microsoft Entra ID (formerly Azure AD), Okta, Google Workspace and OneLogin articles.


    The following details vary depending on the IdP you selected in the previous step: the link to the appropriate support article, suggested values for these two fields, and helper text displayed on the right side of the Authentication configuration section.

    In the Identity provider URL field, enter the IdP's OIDC well-known configuration endpoint. As displayed to the right of the Identity provider URL field, common formats include:

    Microsoft Azure:
    If you are unsure of your tenant ID, follow the instructions located here to find it.
    https://login.microsoftonline.com/{tenant}/v2.0/.well-known/openid-configuration
    Okta:
    https://{yourOktaDomain}/.well-known/openid-configuration
    OneLogin:
    https://{subdomain}.onelogin.com/oidc/2/.well-known/openid-configuration
    Other:
    https://{OIDCDomainURL}/.well-known/openid-configuration

    In the Client ID (Password Sync) field, enter the client ID of the OIDC application configured in the identity provider's platform.
    FIfQ7SL9MBJi7YecmI9L4Ik04ywddpWXRw

  3. Select the Authentication mode. If you have multifactor authentication (MFA) policies configured with your IdP, select Web Login to enforce them.
    KJD5XISEytdK13K_Hh3KNHwt6SNfkQv06w

  4. If you selected Mac Login and your IdP app is configured with a client secret, enter it in the Client secret (optional) field.

    If you are using Microsoft Azure, the "Client Secret" is the Client Secret Value, not the Client Secret ID. Using the Client Secret ID will result in login errors.


    7IwkX8k_dOKAe7zxhPJYoH8MswVPspnnIw

  5. If you selected Web Login, the Library Item displays different options for different identity providers. If you selected Microsoft Azure or Okta in the Identity provider field, enter the redirect URI in the Redirect URI field.
    41WA30XoWdeBHOO6B10rgpSBxtPeFw2IjQ

    If you selected OneLogin in the Identity provider field, you must configure a second OneLogin application that uses the POST authentication method, then enter the information from the second OneLogin application in the Client ID (Web Authentication), Redirect URI, and Client secret fields.

    6FRsDx2cjIWMzvAOpckUUZR-oKWGsAufpg

    If you selected Other in the Identity provider field, you must configure a second OIDC application that uses the authorization code grant, then enter the appropriate information from the second OIDC application in the Client ID (Web Authentication) and Redirect URI fields. Additionally, if the second OIDC application uses a client secret, enter it in the Client secret (optional) field.

    Cqoebim4tj2nJ8ozvUOOSAnoEMsfQpbtCQ

User Provisioning

Configure the user provisioning settings you want to be applied when a user first logs in to the Mac. You can set the default account type and what to do when an account already exists.

Passport uses two attributes of a local Mac user account (which you can view using the dscl command or the Directory Utility app):

  • dsAttrType:io.kandji.KandjiLogin.LinkedAccount: contains a unique value specific to the IdP account; this varies and could be a number, email address, or unique identifier
  • dsAttrType:io.kandji.KandjiLogin.LinkedAccountName: contains a value from the RecordName attribute of the linked user account, for example, an email address

Passport also adds an additional value to the RecordName attribute, the email address of the IdP account.

When Passport creates a new local user account, Passport creates the local Mac account with the appropriate attributes and values.

When Passport merges with an existing local user account, Passport adds a value to the existing RecordName attribute, adding the two additional attributes and values to the existing local user account.

  • User account type
    When new user accounts are created, they can be Administrator (default), Standard, or Specify per identity provider group
    • If you select the user account type as Administrator or Standard, then Passport will check a local account's permissions at the initial Passport login.
    • If you select Specify per identity provider group to configure the new account type based on IdP group membership:
      • Ensure the group in the Identity provider group field in Kandji matches the group in your IdP
        • For Microsoft Entra ID, based on Microsoft's recommendations, use the Entra ID group ObjectID instead of the group name.
        • For Google Workspace, the name entered should be the email prefix of the group in Google as opposed to the name of the group.
      • If a user is designated as an administrator in one group and a standard user in another, that user's account type will be Administrator.
      • When using the option to Specify per identity provider group, Passport checks the user's group membership every time the user logs in. Passport updates the user's account type if you make a group membership change or a configuration change that would cause a user to:
        • change from a standard account to an administrator account
        • change from an administrator account to a standard account (this change forces the user to restart their Mac to demote the user account and ensure that the change is in effect)
  • Ask to merge with a local user
    When a new user logs in to the Mac, they can be offered the option of merging with an existing account. This option will only be shown once per user on the Mac.
    • Never. When a user logs in using their IdP credentials, Passport will create a new user account on the Mac, regardless of existing accounts. This is the default setting.
    • If a local username matches. When a user logs in to the Mac using their IdP credentials, Passport will automatically find the Mac account with a matching username and prompt the user to migrate it. The user will not have the option to migrate to another account.
    • Always. When a user logs in to the Mac using their IdP credentials, Passport will prompt the user to select an existing local Mac account they want to migrate. This is a good option if you are unsure whether or not your users' IdP account names match their Mac account names. When Always is selected, you will see two additional options:
      • Migrate existing account only prevents the user from creating a new Mac account; they will only have the option to migrate an existing account.
      • Exclude local users allows you to list Mac accounts that you do not want the user to migrate. A common use case is preventing the user from being prompted to migrate an IT admin or service account.

sMRk-6p4gqM3KBmldsnmJCaAOaaeAbRa7g

Passport will never delete a local Mac account.

Access

Configure which users can log into the Mac and FileVault's automatic login behavior. For in-depth information regarding password management using Passport, read through the Passport & Managing Passwords article.

  1. Local user access
    • Allow all local users to log in allows all local users to log in to the Mac at the Passport login window. If the Mac is connected to a network and can reach the IdP, Passport will check the user's credentials against the IdP. If the Mac is not connected to a network, the user can log in with their local Mac account credentials. This is the default setting.
    • Allow local administrators to log in allows only local administrator users to log in to the Mac at the Passport login window.
    • Specify which local users can log in allows only users you specify to log in to the Mac at the Passport login window.
  2. Automatic FileVault Login
    • By default, Allow automatic FileVault login is disabled. This ensures the user is presented with the Passport login window when they turn on their Mac. The user must log in at the FileVault login window and again at the Passport login window.
    • If Allow automatic FileVault login is enabledusers will log in only at the FileVault login window but will not see the Passport login window unless they log out. The FileVault login window does not check credentials against an IdP.
  3. Store user password
    • Securely store password: Stores the user's IdP credentials in a dedicated keychain on their Mac to aid in password changes. When the user changes their password with their IdP and then logs in to the Mac, they only need to enter their new credentials; Passport will silently update the Mac password. If a user is already logged in and changes their password with the IdP, Passport will prompt them within 5 minutes to update their local password, and the user will not have to provide their local password; they will only have to enter their IdP password for Passport to change their local password to match their IdP password. The location of this keychain is /Library/Keychains/kandji.keychain. If you remove that keychain, Passport will automatically create a new keychain in that location and use it without generating an error or notification to the user.
      • Web Login Passthrough: When this option is selected with Web Login, users will see an additional password verification screen only the first time they log in. The login process will be completed after a single authentication at the Web Login window on subsequent logins.
    • Do not store password: The user must enter their old and new passwords on the Mac anytime they update their IdP password.

YLWRijVw958rbHPYkgSdHNL91Tz20QiTJw

Customize Login Window

You can customize the Passport login window for your users. Click Customize to reveal the Customize login window drawer with the following options:

  1. Branding
    • Display logo: If you configure your Passport Library Item to use the Web Login authentication mode, Passport displays the web view window instead of the logo. If the user clicks the Local Login button, Passport displays the logo along with username and password fields, instead of the web view window.
    • Customize Desktop picture: A 3840x2160 pixel image is recommended for a background image file.
  2. Menu bar (defaults to enabled) The default setting will display the Wi-Fi menu, allowing users to connect to Wi-Fi at the Passport login window if they aren't already connected.
  3. Banners (defaults to Use system settings)
    • Lock message
    • Policy banner
  4. Power controls (defaults to display all power controls)
    • Shutdown button
    • Restart button
    • Sleep button
  5. Username
    • Customize username label: Enter a custom label for the username field to help users know which credentials to enter at the Passport login window.
  6. Password
    • Include password reset URL: Provide users with a URL to reset and update their IdP password.

Vzgz1Ipiz55Y7Jul0GpO5DxhhvqF_bLMaQ

Customize Help Window

In the bottom left of the Passport login window, users can click the Help icon to display a Help window. You can customize that Help window. Click Customize to reveal the Customize Help window drawer with the following options:

  1. Support tab
    • The Support tab allows you to enter a custom header and body text. This is a great place to explain the Passport login window and how to contact the help desk or get support.
  2. Device info tab
    • Device information is great for troubleshooting and determining what Mac a user is working on. You can enable:
      • Serial number
      • IP address
      • Hostname
      • macOS version
      • Model information
  3. About
    • Displays the version of Passport running on the Mac.

KT6LxijyMdaSxVydIroo6cxaqs7wvCQYaA

Testing Passport

To test various configurations, you might decide to try out various Passport configurations on a test Mac. After changing the Passport Library Item for a Blueprint that a Mac is enrolled in, you can use `sudo kandji library` to force the new Passport Library Item configuration to be applied.

You can use Users & Groups settings (or Users & Groups preferences) to delete a user account associated with Passport.

And in the Finder, you can remove the /Library/Keychains/kandji.keychain, and Passport will automatically create a new keychain if necessary.

After you've performed these steps, you can safely log out and then attempt to log in again with new Passport settings, using the credentials of a test IdP user account.