XCreds Admin Guide

You are here:

Sync Your Cloud Password to your Mac

How It Works

XCreds has two components: the XCreds app that runs in user space and XCreds Login window that is a security agent that runs when the user is logging in to their Mac. Both the security agent and the app share keychain items in the user’s keychain to keep track of the current local password and the tokens from the cloud provider. Both items prompt the user with a web view to authenticate to their cloud provider, verify login was successful, and then update the local password and user keychain passwords as needed.


XCreds currently works with Azure and Google Cloud as an OIDC identity provider. It has been tested on macOS 14 Sonoma, 13 Ventura, and 12 Monterey but should support earlier versions of macOS.


XCreds consists of XCreds Login and XCreds app. They do similar tasks but run at different times.

XCreds Login

XCreds Login is a Security Agent that replaces the login window on macOS to provide authentication to the cloud provider. It presents a web view at the login window and fully supports multi-factor authentication. When authentication completes, the web view receives OpenID Connect (OIDC) tokens and stores those tokens in the login keychain. If the local password and the cloud password are different, the local password is updated to match the cloud password and the login keychain password is updated as well. The local password is then stored in the user keychain so that any password changes in the future can be updated silently. Only the security agent and the XCreds app are given permission to access the password and tokens.

XCreds App

The XCreds app runs when the user logs in. On first launch, it checks to see if XCreds tokens are available in the login keychain. If they are, the refresh token is used to see if it is still valid. If it is invalid (due to a remote password change), the user is prompted with a web view to authenticate with their cloud credentials. If they authenticate successfully, the tokens are updated in the login keychain and the password is checked to see if it has been changed. If it changed, the local account and login keychain are updated to match the cloud password.


Download XCreds from the XCreds product page.


To get started with XCreds, follow the instructions below. All resources are within the app itself and setup is configured using command line tools inside the app bundle. Preferences are handled by configuration profiles (see below).

  1. Install the XCreds package. This will install XCreds.app into your application folder. In post-install, a security agent and a launch daemon are activated. See setup step 4 below.
  2. Install a configuration profile by follow the instructions below under the Configuration section.
  3. Launch the app by double clicking on it. A new menu item will appear with chasing arrows. A web view will also appear since there are no XCreds tokens in the keychain. Authenticate with your cloud password. You will be prompted for your local password and your local password and keychain password will be updated if it is different from your cloud password.
  4. XCreds Login is automatically activated when installed. The installer runs this command: sudo /Applications/XCreds.app/Contents/Resources/xcreds_login.sh -i. This will install an XCreds security agent called XCredsLoginPlugin.bundle in /Library/Security/SecurityAgentPlugins and a launch daemon called com.twocanoes.xcreds-overlay.plist in /Library/LaunchDaemons. The launch daemon shows an overlay on the standard login window to return back to XCreds Login. The authorizationdb is also updated to activate the Security Agent and you can see the new rules by running: security authorizationdb read system.login.console. A backup copy of the replaced rules is stored in /Library/Application Support/xcreds/rights.bak.
  5. Log out of the Mac. The XCreds Login window will be presented. Log in with your cloud credentials.
  6. XCreds.app will not launch automatically. You can use Login Items in System Preferences to automatically launch XCreds.app or use an MDM policy.


Configuration and settings are handled from a config profile. The discovery URL and client ID values are required. All others are optional. Example mobileconfig files are provided in the instructions for each cloud provider.

Azure Setup

See Azure setup instructions.

Google Cloud Setup

See Google setup instructions.

Okta Setup

See Okta setup instructions.


  1. To remove XCreds Login, restore the backup security agent rules and remove the launch agent, run: sudo /Applications/XCreds.app/Contents/Resources/xcreds_login.sh -r
  2. Drag the XCreds app to the trash.


Basic setup for each cloud provider will work by just installing the example mobileconfig file provided in the instructions for each cloud provider (after updating the relevant account ID values). An XCreds settings mobileconfig file can be edited using a text editor for basic changes. To change additional preferences, though, the easiest way is to use Profile Creator. Profile Creator can create a new mobileconfig file that sets all desired preferences. Install and launch Profile Creator. Then click the “+” button near the top left of the window to create a new profile. Give the profile a name and set Payload Scope to be System . Next find the navigation bar on the left below where it says No payloads. This navigation bar will show icons for a check mark, an Apple logo, and an App Store logo. Click the App Store logo icon. Then scroll all the way to the bottom and find the line for XCreds. Drag XCreds from the bottom up to the top left below the item that says “General – 1 payload”. Click on this new item named XCreds below the item named General. Once this is done Profile Creator will show a form with information and options for all XCreds preferences. The following preference keys can then be set and managed.

ADDomainstringThe desired AD domain
clientIDstringThe OIDC client id public identifier for the app.
clientSecretstringClient Secret sometimes required by identity provider.
CreateAdminUserbooleanWhen set to true and the user account is created, the user will be a local admin.
CreateAdminIfGroupMemberarrayList of groups that should have its members created as local administrators. Set as an Array of Strings of the group identifier.
shouldSwitchToLoginWindowWhenLockedbooleanWhen set to true and the user locks the current session, XCreds will tell the system to switch to Login Window. The current session will stay active but the user will login with the XCreds Login Window to resume the session.
discoveryURLstringThe discovery URL provided by your OIDC / Cloud provider. For Google it is typically https://accounts.google.com/.well-known/openid-configuration and for Azure it is typically https://login.microsoftonline.com/common/.well-known/openid-configuration.
EnableFDEbooleanEnabled FDE enabled at first login on APFS disks.
EnableFDERecoveryKeybooleanSave the Personal Recovery Key (PRK) to disk for the MDM Escrow Service to collect.
EnableFDERecoveryKeyPathstringSpecify a custom path for the recovery key.
EnableFDERekeybooleanRotate the Personal Recovery Key (PRK).
loginWindowWidthintegerLogin Window webview width (Integer). If this is not defined, it will be full width. Minimum value of 100.
loginWindowHeightintegerLogin Window webview height (Integer). If this is not defined, it will be full height. Minimum value of 100.
loginWindowBackgroundImageURLstringURL to an image to show in the background while logging in. Default value: file:///System/Library/Desktop Pictures/Monterey Graphic.heic.
passwordChangeURLstringAdd a menu item for changing the password that will open this URL when the menu item is selected.
redirectURIstringThe URI passed back to the webview after successful authentication. Default value: xcreds://auth/
refreshRateHoursintegerThe number of hours between checks. Default value: 3. Minimum value: 0. Max value: 168.
refreshRateMinutesintegerThe number of minutes between checks. Default value: 0. Minimum value: 0. Max value: 59. This value is added to refreshRateHours.
scopesstringScopes tell the identify provider what information to return. Note that the values are provided with a single space between them. Provide the following values the follow IdPs: Google: profile openid email Azure: profile openid offline_access Note that Google does not support the offline_access scope so instead use the preference shouldSetGoogleAccessTypeToOffline. Azure provides unique_name which is mapped to the local user account by using the prefix before “@” in unique_name and matching to the short name of a user account. Google provides “email” and is matched in the same way.
shouldSetGoogleAccessTypeToOfflinebooleanWhen using Google IdP, a refresh token may need be requested in a non-standard way.
shouldShowCloudLoginByDefaultbooleanDetermine if the Mac login window or the cloud login window is shown by default. When not set or set to true, show cloud login. If false, shows Mac login.
shouldPreferLocalLoginInsteadOfCloudLoginbooleanFavor using XCreds’ local login screen over the cloud login UI.
shouldVerifyPasswordWithRopgbooleanWhen verifying password in the menu app, use ROPG.
ropgClientIDstringROPG Client ID for use when checking password
ropgClientSecretstringROPG Client Secret for use when checking password
autoRefreshLoginTimerintegerTimer for automatically refreshing login screen in seconds. If set to 0, does not automatically refresh.
cloudLoginTextstringText for return to cloud login on Mac login screen
shouldShowAboutMenubooleanShow the About Menu item menu. Default value: true
shouldShowRefreshBannerbooleanShow text at the top of the prompt window when tokens expire.
shouldShowConfigureWifiButtonbooleanShow Configure WiFi button in XCreds Login.
shouldShowPreferencesOnStartbooleanShow Settings on start if none are defined. Default value: false
shouldShowMacLoginButtonbooleanShow the Mac Login Window button in XCreds Login.
shouldShowLocalOnlyCheckboxbooleanShow the local only checkbox on the local login page 
usernamePlaceholderstringPlaceholder text in local / AD login window for username
passwordPlaceholderstringPlaceholder text in local / AD login window for password
shouldShowSupportStatusbooleanShow message in XCreds Login reminding people to buy support.
shouldShowQuitMenubooleanShow Quit in the menu item menu. Default value: true
shouldShowVersionInfobooleanShow the version number and build number in the lower left corner of XCreds Login.
showDebugbooleanShow push notifications for authentication progress. Default value: false
usernamestringWhen a user uses cloud login, XCreds will try and figure out the local username based on the email or other data returned for the IdP. Use this value to force the local username for any cloud login. Provide only the shortname.
KeychainResetbooleanReset the keychain without prompting if the login password doesn’t match the local password.
PasswordOverwriteSilentbooleanUpdate the password silently to the new one. Used with the KeychainReset if the user has a secure token.
localAdminUserNamestringUsername of local admin user. DO NOT SET THIS IN PREFERENCES. It is recommended to set this with the settingsOverrideScriptPath script. This user is used to reset the keychain if the user forgets their local password and to setup a secure token for newly created users.
localAdminPasswordstringPassword of local admin user. DO NOT SET THIS IN PREFERENCES. It is recommended to set this with the settingsOverrideScriptPath script. This user is used to reset the keychain if the user forgets their local password and to setup a secure token for newly created users.
verifyPasswordbooleanWhen cloud password is changed and the local keychain password and local user account needs to be changed, a verification dialog can be shown to verify the password. Default value: true
shouldDetectNetworkToDetermineLoginWindowbooleanCheck if network is up. If not, select username and password login window.
idpHostNamestringHostname of the page that has the password field. When the user submits the form, XCreds will use idpHostName to identify a page it needs to look for the password field. The password value is identified by an HTML id defined by passwordElementID. If this value is not defined. XCreds will look for login.microsoftonline.com and accounts.google.com. This value is commonly set for other IdP’s and for Azure environments that use ADFS.
idpHostNamesarrayarray of hostnames of the page that has the password field.
passwordElementIDstringPassword element id of the html element that has the password. It is read by using JavaScript to get the value (for example, for Azure, the JavaScript document.getElementById(‘i0118’).value is sent. If this default is not set, standard values for Azure and Google Cloud will be used. To find out this value, use a browser to inspect the source of the page that has the password on it. Find the id of the textfield that has the password. Fill in the password and then open the JavaScript console. Run: document.getElementById(‘passwordID’).value changing “passwordID” to the correct element ID. If the value you typed into the textfield is returned, this is the correct ID.
map_firstnamestringLocal DS to OIDC Mapping for First Name. Default value: “given_name”. map_firstname should be set to an OIDC claim for first name.
map_lastnamestringLocal DS to OIDC Mapping for Last Name. Default value: “family_name”. map_lastname should be set to an OIDC claim for last name.
map_fullnamestringLocal DS to OIDC Mapping for Full Name. Default value: “name”. map_fullname should be set to an OIDC claim for full name.
map_usernamestringLocal DS to OIDC Mapping for Name. Default value: “name”. map_username should be set to an OIDC claim for name.
settingsOverrideScriptPathstringScript to override defaults. Must return valid property list with specified defaults. Script must exist at path ,be owned by _securityagent and writable and executable only by _securityagent.

Preferences Version

The preferences shown on this guide are for the current version of XCreds. When a new version of XCreds is released the new preferences manifest is sent to Profile Creator, however there may be a delay before Profile Creator is updated to reflect these new preferences. If new keys are not yet shown in Profile Creator see more information on how to use new preference keys.

Scripting System Defaults

XCreds preferences can also be configured by using a script to set system defaults. More information is available on how this is done.


Payload Scope

If the current mobile config file used for XCreds settings was recently created with Profile Creator, double-check that Profile Creator has the General tab section for Payload Scope is set to System. If this is left as the default value of User, the XCreds login window web view will display an error or waiting message.

Client ID

Make sure to update the XCreds settings mobileconfig file value for clientID to the value for your identity provider account. For example, in Azure, the clientID can be found from the Azure Portal by searching for App Registrations, then clicking All applications and finding the record used for XCreds. This will show the value to use for XCreds for Application (client) ID.

Redirect URI

It may be necessary to verify the mobileconfig file value for redirectURI. This can be any value but must match configuration set in the identity provide account used. For example, in Azure, go to Azure Portal > App Registrations > All applications. Find the application entry used for XCreds. Click on Redirect URIs and verify the correct value to use in the mobileconfig file or add a new redirect URI in Azure Portal for this.

Background Image URL

The setting for loginWindowBackgroundImageURL should change both the XCreds cloud login window background and the XCreds local login window. The image for this needs to be of type heic, png, or jpeg. Also to be able to see this background on the XCreds cloud login window, the settings for loginWindowWidth and loginWindowHeight need to be set in the profile as well to, for example, 500 each.

Kerberos Ticket

After configuring XCreds for Active Directory and signed in as an AD user, to get a Kerberos ticket the XCreds menubar item needs to be running or should be launched from the Applications folder.

Override Script

When using the configuration for settingsOverrideScriptPath, the script file should be owned by _securityagent and have permissions 700.

For example, for a script located at /usr/local/bin/override.sh, run the following commands:

sudo chown securityagent /usr/local/bin/override.sh
sudo chmod 700 /usr/local/bin/override.sh


When using this preference key it may be necessary to add configuration in the identity provider console. For Azure as an example it is necessary to go to the Azure console, navigate to App Registrations, and find the app registration used with XCreds. Then find Token configuration and click Add groups claim. Then leave all choices as default and click save. Once this is done go to Groups in Azure console, create a new group, and note its Object Id. Once this is done and an Azure user account is assigned to the group, create an XCreds configuration profile and set the CreateAdminIfGroupMember preference key value to be the Object Id for the Azure group that was created. This preference configuration will then allow XCreds to create the related user as an admin when first signing in to macOS.


See the video on Youtube


Please join the XCreds channel on MacAdmins Slack for any questions you have. Paid support is available from Twocanoes Software.


Special thanks to North Carolina State University and Everette Allen for supporting this project.

OIDCLite is Copyright (c) 2022 Joel Rennich (https://gitlab.com/Mactroll/OIDCLite) under MIT License.

XCreds is licensed under BSD Open Source License.