[Feature Request] Ability to get XCreds state via CLI

[bryanheinz]

As I roll out XCreds it would be nice to be able to check on the state of the rollout programmatically by polling my endpoints.

A "simple" solution could be for XCreds to write it's state to disk when it does a password check. A more complex, but long term (in my opinion) more useful solution could be an XCreds CLI tool that has a flag for getting the current state.

[bryanheinz]

I was thinking through potential states that I would like to know about. I'm sure that I'll come up with more as I roll out XCreds 😅 For context, my usage is syncing existing macOS account passwords with an IdP and not utilizing the login window/account creation features – I'm sure using the login window feature would generate other states that would be useful to know about.

• 'Initializing' – on first launch, the user hasn't entered their password and synchronized with the IdP. I want to know who's putting off syncing.
• 'Synchronized' – Local and IdP passwords are synchronized.
• 'Out of Sync' – Password differs between local and IdP and has had at least one successful initial synchronization.
• 'Error' – Any sort of catch-all error state. Ability to get the error message via CLI would be excellent. More specific error states might be useful, but I won't know what those are until I run into them.

A related, but not necessarily a "state", info item would be the connection method/IdP – i.e. Active Directory, Azure IdP, Google IdP, Okta IdP, etc. This would help anyone who is in-between/switching methods/IdP's poll what endpoints are using what system.

[twocanoes]

Is this still wanted? waiting for more upvotes / feedback.

[bryanheinz]

I'd still love to have this feature. While I’ve already rolled out XCreds, I'd still like to be able to output its status via CLI. I could then write a MunkiReports module, for instance, to get a birds eye view of my fleet and proactively reach out to users to resolve XCreds issues we might catch.

[twocanoes]

OK, i could implement it this way:

Initializing: no xcred entries in the keychain means no syncing happened.

Synchronized: I can only go by the last sync date. Not sure how I can tell if the current login password is the same as the IdP given that the IdP could have changed since the user last logged in. Perhaps not if they cancelled when prompted?

Out of Sync: I can only go by the last sync date. Not sure how I can tell if the current login password is the same as the IdP given that the IdP could have changed since the user last logged in. Perhaps not if they cancelled when prompted?

Error: Other?

Another option is to provide a "last synced" date for the user account and leave it up to you to determine what that means.

[bryanheinz]

Sorry for the delayed response. First, I wouldn't hold back v5 for this. I'd rather see v5 released and collaborate on this than rush this out the door or hold v5 back for this.

The goal with my XCreds CLI request is to know the state that XCreds is in. The thought spawned from looking at the XCreds menu app "Credentials Status: " and wondering if that data was exposed anywhere for me to run reports on.

Reviewing your notes, it sounds like reporting the last successful sync status might be best and to nix the 'Synchronized' and 'Out of Sync' states I mentioned.

Would there be a way to report if there were any sync errors?

What about reporting the "Credentials Status" that I see in the menu bar?

I quickly browsed through the XCreds code and saw a few enum's that might be interesting to check via CLI. I'm curious if it'd be possible or even make sense to securely expose them:

• PasswordUtils : PasswordError
• PasswordUtils : PasswordVerificationResult
• KeychainUtil : KeychainError

I'm greedily looking for any data that I can get my grubby little hands on to build out status dashboards or probe endpoints for issues without having to take over a user's computer.

I appreciate you looking into this with me ✌️

-bryan

[twocanoes]

I added a CLI interface to 5.2 (as of build 7289). I only have a few commands for status so far:

Mac:~ tperfitt$ /Applications/XCreds.app/Contents/MacOS/XCreds -h
OVERVIEW: Command line interface for XCreds.

USAGE: xcreds

OPTIONS:
-h, --help Show help information.

SUBCOMMANDS:
status Get status of XCreds
import-users Import users from a CSV for RFID login. Format:Full
Name,Username,Password,UID,RFID-UID. All imported
user data is encrypted with a ECC stored in the
system keychain and the encrypted data is stored in a
file located in /usr/local/var/twocanoes. The file is
only readable by root.
import-user Import an RFID user.
show-user Show RFID user.
show-users Show RFID users.
update-admin-user Set the current admin user used for resetting
keychain.
show-admin-user Show currently set admin user. Used for resetting
keychain.
clear-admin-user Clear the current admin user used for resetting
keychain.
clear-all-users Clear all users. Does not clear the admin user.
list-readers Listen and print the RFID of scanned cards.
rfid-listener Listen and print the RFID of scanned cards.
run-app (default) Start app normally.

See 'xcreds help ' for detailed help.

status shows:

Password:
----- CONSOLE RIGHTS -----
builtin:prelogin
builtin:policy-banner
loginwindow:login
builtin:login-begin
builtin:reset-password,privileged
loginwindow:FDESupport,privileged
builtin:forward-login,privileged
builtin:auto-login,privileged
builtin:authenticate,privileged
PKINITMechanism:auth,privileged
builtin:login-success
loginwindow:success
HomeDirMechanism:login,privileged
HomeDirMechanism:status
MCXMechanism:login
CryptoTokenKit:login
loginwindow:done
----- OIDC User Info -----
test
localUsername:test
oidcUsername: test
mblackwell
localUsername:mblackwell
oidcUsername: mblackwell

You said you wanted "The goal with my XCreds CLI request is to know the state that XCreds is in".

Do you mean of the current logged in user? So add a section with "current user", give the username, say what the token state is, etc?

Also, you can get the output as JSON with the --json flag.

tim

[bryanheinz]

Hey Tim, thanks for the update! --json output is ::chef kiss::

Personally, I don't need the current logged in user, but I could see other people finding that useful.

My orgs usage of XCreds is "make your macOS password your IdP password". I'm looking for information like:

• Did the user ever initialize XCreds? (I.e. go through the initial XCreds flow to set their Mac password to their IdP password? We're not using the XCreds LoginWindow.)
• Is their Mac password currently in sync with their IdP password? (it sounds like this might not be possible)
• A general Healthy/Unhealthy status ("XCreds is working as expected, things are in sync and tip-top" or "here be dragons, you should investigate")
• Token state would be great

A couple of extras that I think could be useful:

• License state (Trial/Valid/Expired/[Other?])
• Version (just a simple output of the installed version)

An example usage of this using MunkiReport widgets:

• Display a count of endpoints with incomplete setup (status: unhealthy; errors: incomplete setup)
• Display a count of unhealthy endpoints (status: unhealthy)
• Display a count of endpoints with expired license (license: expired — whoops, did we forget to renew? or maybe some endpoints need the license redeployed?)
• Display a count of healthy endpoints (yay, look boss — happy green numbers! 🎉 )

Click into any of those widgets to see the list of computers with the status, click on the computer to see the error details.

This is the future state that I'd love to be in.

---

Here's some rough example output I through together:

Status: Healthy
Errors: None
Tokens: Valid
Password: Matched
License: Valid
Version: 5.2.0.7289

Status: Unhealthy
Errors: Invalid IdP tokens.
Tokens: Invalid
Password: Unknown
License: Valid
Version: 5.2.0.7289

Status: Unhealthy
Errors: Passwords do not match.
Tokens: Valid
Password: Mismatch
License: Valid
Version: 5.2.0.7289

Status: Unhealthy
Errors: Setup incomplete.
Tokens: Invalid
Password: Unknown
License: Valid
Version: 5.2.0.7289

Status: Unhealthy
Errors: Setup incomplete. Mismatched passwords.
Tokens: Invalid
Password: Unknown
License: Valid
Version: 5.2.0.7289

Status: Unhealthy
Errors: License/trial expired.
Tokens: Valid
Password: Matched
License: Expired
Version: 5.2.0.7289