This article assumes that you are using OneLogin Desktop for Mac 2.1. If your organization is using OneLogin Desktop for Mac 2.0.x and the Automatically push new updates default option is selected on the Devices > OneLogin Desktop page, your users will be updated to the new version silently some time after release. If you are using Desktop for Mac 1.x, your users must upgrade manually.
OneLogin Desktop for Mac enables your users to log into their Mac OS X devices using their OneLogin credentials and use a certificate installed in their keychain as an authentication factor when they access their OneLogin portal page and SSO-enabled browser-based apps on a trusted device. In other words, your users can log in once to their Macs and go straight to their OneLogin portal or their SSO-enabled apps without having to provide credentials again.
OneLogin Desktop enables you, as the admin, to manage the Mac and Windows devices that use OneLogin Desktop for authentication, without having to set up and maintain your own Active Directory or LDAP directory. You manage devices through a Device Manager dashboard in OneLogin.
In order to enable this authentication process, your users run an installer on their local machines that automatically configures a user account that uses their OneLogin credentials and authenticates against the OneLogin directory. This OneLogin Desktop user account has local admin privileges.
The installer also installs a certificate in the keychain of the new user account. If you choose to let your users bypass "browser SSO," giving them access to OneLogin after logging into their Macs without having to authenticate to the OneLogin portal, OneLogin Desktop uses that certificate to establish trust between OneLogin and the user account on that specific device.
This article describes the administrative tasks required to support OneLogin Desktop for your users. It includes the following topics:
- System requirements
- Configuring OneLogin to support OneLogin Desktop for Mac
- Managing devices
- Locking users out of their OneLogin Desktop account
- Removing a OneLogin Desktop account
- Uninstalling OneLogin Desktop
- Tips for testing OneLogin Desktop
To learn about end-user installation tasks and how to use a OneLogin Desktop account on a client Mac, see Installing and Using OneLogin Desktop for Mac.
- Mac OS X 10.11+ on the device
- OneLogin subscription must include OneLogin Desktop for Mac
- Device cannot be joined to an Active Directory domain
- Browsers: Chrome or Safari are required to use the certificate to provide access to the OneLogin portal or SP-initiated SSO without having to reauthenticate
Configuring OneLogin to support OneLogin Desktop for Mac
Log in to OneLogin as an admin.
Go to Devices > OneLogin Desktop and select the Mac tab.
Toggle the Enable OneLogin Desktop Service For Mac button on.
This enables your OneLogin Cloud Directory to authenticate Mac users against OneLogin.
- (Optional) Give your users the ability to go straight to their OneLogin portal or SSO-enabled apps without logging in.
If you want users who have authenticated to their Mac device to be able to go straight to the OneLogin portal and their SSO-enabled apps without being prompted to log into OneLogin, you must create or update a user policy that enables this browser login bypass:
Click the user policies link or go to Users > Policies.
Click New User Policy or select an existing user policy to update.
Under Trusted Devices, select Don’t require browser login for trusted devices.
Note that this option appears only if you have already enabled the OneLogin Desktop Service for Mac in step 3, above.
Assign the policy to the appropriate users.
For more information about creating and assigning user policies, see User Policies.
Download the OneLogin Desktop installer and run it on a test Mac device, using a test OneLogin account.
Follow the instructions in Configuring a Mac client to support OneLogin Desktop for Mac.
The installer lets you enable OneLogin Desktop for an existing local account or create a new local user account that authenticates against OneLogin. Use the test OneLogin account when you are prompted by the installer to authenticate to your OneLogin subdomain.
If you can log in to your Mac device successfully using the test account, turn on the Enable Download toggle to provide the installer to your users so that they can install it on their devices themselves.
Your users will be able to download the installer from the OneLogin portal by going to the Security tab on their Profile page.
(Optional) Toggle Automatically push new updates on to push OneLogin Desktop for Mac updates to your users so that they don't have to download new installers and run the installers themselves.
This option is enabled by default.
OneLogin provides a Devices dashboard that lets you manage the Mac and Windows devices that use OneLogin Desktop for authentication. Go to Devices > Devices.
You can search by user or device name and filter by device type (operating system) and status (Trusted or Registered).
A Trusted user/device is one that can use a certificate as the authentication factor in place of passwords and MFA when authenticating to OneLogin. A Trusted user account/device is one that allows the user to log in using their OneLogin credentials and go straight to their OneLogin portal or SSO-enabled, browser-based apps without authenticating again using the browser. By definition, a Trusted user account is one that is assigned to a User Policy enabled for Trusted devices.
A Registered user/device is one that has had OneLogin Desktop installed but cannot use a certificate (if installed) in place of browser login using a password (and MFA if required). Registered users authenticate against OneLogin to access their user account on their device.
Click a user/device row to view details and remove Trusted status for a user.
Remove revokes the certificate and makes the user untrusted for that device. The user will no longer be able to skip browser authentication, but will continue to be able to log in to their OneLogin Desktop account on their Mac. Once you remove the device, you will no longer be able to see it in your dashboard. Note that to lock the user out of the OneLogin Desktop account on their Mac, you must also change the user's password or suspend or delete the user's account in OneLogin.
You can also view a user’s OneLogin Desktop-authenticated devices by going to the Devices tab on the user record (Users > All Users > select the user).
Locking users out of their OneLogin Desktop account
If you need to lock a user out of the OneLogin Desktop account on their Mac, you can do one of the following:
Suspend or delete the user's account in OneLogin
Change the user's password and deny them the ability to reset their password in OneLogin
Note that if the user is offline when you delete or suspend their account or change their OneLogin account password, the user will continue to be able to access their account until they go online.
Removing the OneLogin Desktop account from a Mac
You can disable a OneLogin Desktop account on a Mac by removing the account's user profile from the Users & Groups list on the Mac and removing the device from the Devices dashboard in the OneLogin admin portal. However, when you do this, you also:
- Remove the entire user home directory for the account, including all files that aren't shared
- Leave OneLogin Desktop assets installed on the Mac
If you want to uninstall OneLogin Desktop entirely from a Mac, follow the instructions in Uninstalling OneLogin Desktop for Mac instead.
If you want to switch ownership of an existing local account--including an existing OneLogin Desktop-enabled account--to a new OneLogin user, you can use the installer. See Installing and Using OneLogin Desktop for Mac.
Note. You do NOT need to remove the OneLogin Desktop account to update from Desktop 2.x > 2.y.
To remove a OneLogin Desktop-enabled account (user profile) from a Mac:
Log in as an admin user that is not your OneLogin user account.
Go to System Preferences > Users & Groups.
Click the lock icon to enable changes (if necessary).
Select the OneLogin user account and click the - minus sign to remove the account.
When prompted, confirm that you want to remove the user.
If you are removing a Desktop for Mac 1.x or 2.0.x account, click Login Options and then select Network Account
ldap.eu.onelogin.com) to remove it.
Follow all prompts.
To remove the device from your Devices dashboard, log in to OneLogin as an admin, go to Devices > Devices, select the device, and click the Remove button on the device details dialog.
Uninstalling OneLogin Desktop for Mac
Note. You do NOT need to uninstall OneLogin Desktop to update from Desktop 2.x > 2.y.
You can disable a OneLogin Desktop account on a Mac by removing the account's user profile from the Users & Groups list on the Mac or by locking the user out of OneLogin. However, the installed OneLogin Desktop assets (the PAM module and config script) remain on the Mac in these cases.
To completely uninstall OneLogin Desktop for Mac, you must remove the PAM module and config script from the Mac and remove the device from the Devices list in the OneLogin admin portal. You can continue to use the former OneLogin Desktop account as a local account.
To uninstall OneLogin Desktop and continue using the former OneLogin Desktop account as a local account:
If you are logged in to the account (user profile) that is enabled for OneLogin Desktop, log out.
Log into another local admin account (not the OneLogin Desktop account).
Open Terminal and run:
$ cd /Library/Frameworks/OneLogin.framework/Versions/Current
Run the following command:
$ sudo ./pam_onelogin_config.sh uninstall
Log into the OneLogin Desktop account with the OneLogin password.
Go to System Preferences > Users & Groups and change the password for the OneLogin Desktop account.
Log out of the OneLogin Desktop account.
Log into the other local admin account.
Open Terminal and run the following command to remove the OneLogin PAM module:
$ sudo rm -rf /Library/Frameworks/OneLogin.framework
Confirm that the directory was successfully removed:
$ cd /Library/Frameworks/OneLogin.framework/Versions/Current
No such file or directory
You should now be able to log into the former OneLogin Desktop account with the new password that you configured in step 6.
Log in to OneLogin as an admin and remove the device from the Devices dashboard.
Go to Devices > Devices, select the device, and click the Remove button on the device details dialog.
Tips for testing Desktop for Mac
If you're evaluating and therefore installing and reinstalling OneLogin Desktop on the same machine, you should keep the following in mind:
Verify that your Mac meets the "System Requirements" listed in Installing and Using OneLogin Desktop for Mac.
You can install up to two OneLogin Desktop accounts on a single machine for testing purposes (you should not install more than one on an active user's Mac), but certificate-based browser SSO is only supported for one account per machine. The certificate will only work on the last account installed.
Never enable OneLogin Desktop for the only admin account on your machine; you should always have a local admin account in addition to your OneLogin Desktop account.
You don't need to delete any user profiles before you reinstall OneLogin Desktop.
Don't change the user password locally; always change your password in OneLogin.
For a list of frequently-asked questions, see the end-user documentation at Installing and Using OneLogin Desktop for Mac.