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 using this Early Access Product.

 

Supported macOS versions:

• macOS 10.12.x - Sierra
• macOS 10.13.x - High Sierra
• macOS 10.14.x - Mojave
• macOS 10.15.x - Catalina
• macOS 11.x - Big Sur
• macOS 12.x - Monterey
• macOS 13.x - Ventura

 

Recommended: Using a Virtual Machine

Since this product is still in Early Access, we highly recommend using a VM instead of your actual operating system as you can potentially lock yourself out of your machine. 

 

Recommended: 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. 

 

Recommended: 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. 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 Login Plugin. Currently, this is only available if you have contacted Sales. 

2. When you reach the "Evo Config" step and are prompted to enter values, follow this key:

1. 1. 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 /
   2. Evo Directory: This is the Evo Directory where the users are stored. If this is an Evo Cloud directory, make sure you append “_local” to the end of it. An example would be “mactesting_local”.
   3. 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. NOTE: This is not required, but HIGHLY recommended.
   4. API Key: This is the “Secret Key” that is generated when creating an Access Token. NOTE: If you do not plan on using Elevated Access, this field is optional.
   5. Access Token: This is the Access Token that is generated under the Access Token creation. NOTE: Similar to the API Key, this is optional if you do not plan on using Elevated Access.

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!

7. Optional: 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.

8. 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 accept a Push notification.

9. 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. Continue through the installation steps until you get to step 5. On step 5, uncheck “Install Evo Login Plugin” and check “Uninstall Evo Login Plugin”. Continue and observe the app being uninstalled!

 

 

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