This guide will walk you through installing the macOS credential provider. Before installing however, we must recommend some best practices here. This is to ensure that you can recover should something go wrong.
NOTE: Once Evo is installed on a Mac, ANY and ALL users will be required to use Evo to login to the machine.
Supported macOS versions
- macOS 14.x - Sonoma
- macOS 13.x - Ventura
- macOS 12.x - Monterey
- macOS 11.x - Big Sur
Recommendations
Using a Virtual Machine
We highly recommend using a VM instead of your actual operating system as you can potentially lock yourself out of your machine when first testing this product.
Using a Fail-safe User
In addition to using a Virtual Machine, we also recommend using a Fail-Safe user. This is your "break glass" user that has administrative access to your machine that can bypass the credential provider. It is recommended that this is a local administrative account on the machine.
NOTE: The Fail-safe user should NOT be the same as Domain Account used for Elevated Access.
Contact Evo
We are more than happy to support you during this installation period! If you would feel more comfortable with an Evo representative with your during the time of install, please reach out!
With these recommendations and preliminaries noted, we can now begin the install.
Installation
This product has been tested using the Evo Cloud Directory and On-Prem AD using our LDAPS agent. If using the Evo Cloud Directory Solution, before getting started, make sure you have users that exist locally that match your Evo Directory, and those users are fully configured with MFA. Regarding your local machine, if your macOS user is “admin”, there should be an e-mail address such as “admin@example.com under the given Evo Directory.
1. Download and begin installing the macOS DMG File from the portal. (Found under Applications)
2. When you reach the "Evo Config" step and are prompted to enter values, follow this key:
-
- Environment: This is your Evo Environment URL. An example would be https://mactesting.evosecurity.com – Make sure it is typed exactly as follows with the required “https://” beginning and no trailing /
- Evo Directory: This is the Evo Directory where the users are stored. This information is available when you create an access token. Be mindful to add '_local' for directory-as-a-service directories. See the screenshot below as an example.
- Fail-safe User: This is a user that will be excluded from the macOS Credential Provider. They will not need to MFA or exist in an Evo Directory. An example would be a super user you have on your local machine named “superadmin”. Provide that username here. This is case sensitive! Please verify the user's home folder for the username, not as it is displayed on the mac.
- Secret: This is the “Secret Key” that is generated when creating an Access Token.
- Access Token: This is the Access Token that is generated under the Access Token creation.
3. Continue with the installation until it forces you to log out.
4. After logging out, you will be met with a familiar login for your user.
5. After entering the correct password, you now will experience the macOS Credential Provider! You now have two options:
a. You must either enter a correct OTP code for that user and select Submit OTP
b. You must click "Send Push" and accept the push notification on your device.
6. After Successful authentication, you will be allowed into the user profile!
MacOS Elevated Access
If you have set up Elevated Access and wish to complete an action that requires Elevated (admin) authority, you will be presented with our Elevated Access Dialog box.
As the dialog box mentions, you must select the Elevated Login checkbox and input your e-mail and password, and either enter an OTP or SEND a Push notification.
After successful authentication, you are able to complete the elevated action!
Offline Codes
If you are offline, the steps are relatively the same. After you select your user and enter your password, you must then enter the offline code in order to authenticate and proceed. Do note, you will be unable to do any elevated actions while offline, as you are unable to communicate with the Evo server. It would be best to use your fail-safe administrative user to complete any elevated actions necessary in this event.
Uninstalling
If you wish to uninstall the credential provider, run the same download package that you used to install the app as Administrative User.
Find "Evo MacLogin" and click on “Uninstall Evo MacLogin”. Continue and observe the app being uninstalled!
For manual uninstalling: In Terminal (as an Administrative User) navigate to "/Volumes/Evo\ MacLogin/Uninstall\ Evo\ MacLogin" and run the following command:
sudo ./Uninstall\ Evo\ MacLogin
Logging & Debugging
Running into some errors or unsure why something is not working? Logging and Debugging may help. You can access logs specific to each of the login plugin components by running the following commands via the terminal:
log show --predicate 'sender CONTAINS "EvoLogin"'
log show --predicate 'sender CONTAINS "EvoAuth"'
And for the logs specific to the login helper, use the following command:
log show --predicate 'sender CONTAINS "com.evosecurity.EvoLogin.helper"'
Or, to see all logs from a given date/date time:
log show --start '2022-05-19 11:14:24'
To delete all logs (in order to clean up) use the following command but do so at your own risk since this will delete all logs on the device including those not belonging to the login plugin:
sudo log erase --all