Documentation

 

 

Introduction

Login for Mac (available in SecureAuth IdP version 9.2+ only) adds SecureAuth’s Multi-Factor Authentication to the Mac desktop login experience. This product was introduced in SecureAuth IdP version 9.2 and supports the following authentication methods:

  • Timed Passcode
  • Voice Call
  • Passcode sent via SMS / Text Message
  • Passcode sent via Email
  • One-time Passcode via Push Notification
  • Login Notification via Push Notification
  • YubiKey HOTP Device Passcode
  • Passcode from Help Desk

NOTE: Methods delivered via Push Notification require the use of the SecureAuth Authenticate App.

In addition to the supported Multi-Factor Authentication methods, Login for Mac supports the following setups and features:

  • Offline mode login
  • Users in bypass group can skip Multi-Factor Authentication
  • Bypass group lookup on a domain other than user's domain
  • Password expiration notification
  • Multiple login capability
  • Endpoint identified during login Multi-Factor Authentication request
  • YubiKey HOTP support for 2-Factor Authentication
  • TOTP 2-Factor Authentication
  • Adaptive Authentication
  • Validated with FIPS 140-2 compliant cryptographic libraries

Refer to the Release Notes for more information about releases.

DISCLAIMER:

  • Login for Endpoints ONLY supports the samAccountName login name format; userPrincipalName (UPN) is not supported.
    Note that UPN is supported at login, but if using a non-AD profile store containing OATHSeed/OATHToken/PNToken but not samAccountName, then the Multi-Factor Authentication lookup will fail and the user will not be able to use other Multi-Factor Authentication methods.


Prerequisites

Administrator: Setup requirements

1. Ensure SecureAuth IdP v9.2 or later is running and is using a SHA2 or later certificate bound to Microsoft Internet Information Services (IIS). For example, in the IIS Management Console's Default Web Site section, check the Site Bindings section to ensure the https/443 type and port settings have a valid and trusted SHA2 certificate selected, as shown in the following image:

2. Create a new realm or access an existing realm on which more than one Multi-Factor Authentication is required.

NOTE: This realm should not be configured for Single Sign-on.

3. Configure these SecureAuth IdP Web Admin tabs: Overview, Data, Workflow, Multi-Factor Methods, Post Authentication, and Logs.

4. Ensure target end user machines are running any of the following, minimum supported OS versions:

  • macOS High Sierra 10.13.2
  • macOS Sierra 10.12.6

NOTE: See SecureAuth Compatibility Guide for OS and SecureAuth IdP version support information.

User account and Mac workstation requirements

  • The end user Active Directory profile must be accurately configured on the Mac so that the endpoint can retrieve the AD end user profile during the login process.
  • In an enterprise WiFi environment, before setting up Login for Mac on end user workstations, the system level policy must be configured to allow the Mac to connect to the enterprise WiFi. This setup lets Login for Mac fetch the OATH seed which is used to authenticate the end user.
  • If an end user is already using a YubiKey device for YubiKey Multi-Factor Authentication on a SecureAuth IdP realm, the OATH seed and associated YubiKey device must be removed from the end user's account in order to prevent a conflict when the end user attempts to use a YubiKey device for HOTP authentication. (See the steps under End User Multi-Factor Authentication in the YubiKey Multi-Factor Authentication Configuration Guide to remove the YubiKey device from the user account profile.)

NOTE: If an end user is disabled on Active Directory, the local account will not know the history of the AD account, and the user will not be able to log on the Mac.

End users can be locked out of their Mac workstations due to any of these factors:

  • Network Setup Issues
  • Login for Endpoints Installer Misconfiguration
  • End user Mac Configuration Issues

How to Prevent and Troubleshoot End-user Lockouts

Network setup issues

Matching Active Directory profiles required

Active Directory must include an account profile for each end user, and that profile must match the AD profile set up on the Mac in order for the Mac endpoint to retrieve the AD profile.

Login for Endpoints installer misconfiguration

Edits made in config.json file

If the configured config.json file is edited, caution must be taken to ensure Unicode characters — instead of UTF-8 charcters — are not entered and saved in the file. This scenario might occur if text is copied from another source and pasted into the file, and could result in an end user being locked out of the Mac due to a misconfigured endpoint. 

End user Mac configuration issues

Misconfigured Active Directory profile on Mac

If the end user's new Mac has a misconfigured Active Directory account profile, the endpoint will not be able to retrieve the end user's AD profile to complete the login process.

Lockout with secure, automatic enterprise WiFi endpoint connection

If the endpoint is set to automatically connect to a secure, enterprise WiFi, and has not yet been configured to connect to a SecureAuth IdP realm, then the end user will be locked out of logging on the Mac.

In this scenario, the Mac may need to be reset by the administrative user who can bypass the login endpoint in order to reset the machine.

Lockout without OATH seed for YubiKey HOTP device or network connectivity

If a YubiKey HOTP device is used for logging on the Mac, but the machine does not have an OATH seed stored on it or network connectivity, then the endpoint must wait for an available network connection.

If the end user is attempting to log on for the first time, and the Mac does not have WiFi configured or is not using a wired connection, then the end user will be locked out of logging on the Mac.

End user account and Mac workstation requirements 

IMPORTANT: Before installing Login for Mac

Your local username and password on the Mac must be the same as your Active Directory username and password. If you are using a different local username than your Active Directory username, then you will need to contact IT to synchronize the IDs.

If the IDs are synchronized, be sure you can log on the Mac before installing Login for Mac.

First-time usage requirements

The first time you use Login for Mac to log on the network:

A timed passcode is required. You must have an account provisioned with a SecureAuth IdP realm that enables your device to generate timed passcodes for Multi-Factor Authentication:

Your Mac must either be hardwired to the network, or you must have a preconfigured WiFi connection within range to which your Mac can be manually connected.

Thereafter, you can use Login for Mac in the offline mode.


SecureAuth IdP Web Admin configuration

Data tab

1. Create a new realm and configure a data store on the Data tab.

2. In the Membership Connections Settings section, under Group Permissions, select False from the Advanced AD User Check dropdown.

3. Select Bind from the Validate User Type dropdown.

4. In the Profile Fields section, enter adminDescription in an unused Aux ID field—Aux ID 3 in this example—and make the field Writable.

5. If using a single OATH seed for end user Multi-Factor Authentication (see sample Post Authentication page image), then map Fields to OATH Seed and OATH Tokens Properties, as shown in the Profile Fields image below.

 


6. Click Save.

Optional: Adaptive Authentication tab

NOTE: Adaptive Authentication can be used to control the user login experience and to mitigate security risks.

The order of priority to handle user authentication login requests using Adaptive Authentication is as follows:

A. Threat Service

B. IP allow list / deny list

C. Geo-location

D. Geo-velocity

E. User / Group

Multi-Factor Methods tab

7. In the Multi-Factor Configuration section, configure the Multi-Factor Authentication methods you want enabled.

8. Click Save.

System Info tab

9. On the System Info tab, in the Links section, Click to edit Web Config file.

10. In the Web Config Editor section, under <appSettings>, add this line:

    <add key="OTPFieldMapping" value="AuxID#" />

NOTE: In this example, AuxID3 is used since this Property was selected and configured on the Data tab in step 4.

11. Click Save.

API tab

12. In the API Key section, click Generate Credentials.

The API ID and API Key are required and used in the config.json file for all scenarios of using this product.

13. In the API Permissions section, select Enable Authentication API.

NOTE: It is not recommended to enable Identity Management options since the password reset function uses an IdP realm or third party password reset URL—not the Identity Management API.

14. Click Save once the configuration is complete.

15. Select Enable Login for Endpoints API, and then click Configure Login for Endpoints Installer.

Login for Mac Installer Configuration 

16. On the Login for Endpoints Installer Configuration page, select Mac OS as the Endpoint Operating System.

17. Enter the IdP Hostname.

18. Under Multi-Factor Authentication Settings, specify whether or not the user must use Multi-Factor Authentication to access the Mac from a desktop and / or via remote access from another Mac device.

If any user group is allowed to bypass Multi-Factor Authentication, enable the bypass option and list the user group(s).

NOTE: A user group on another domain can be bypassed via the Mac authentication plugin and Pluggable Authentication Modules (PAM) installed on the end user's workstation. In this scenario, the Open Directory API can be used by specifying the user group and domain.

19. Click Download Installer Config to download the JSON file (config.json) that will be used with the PKG file, as described in the Installation section of this guide.

NOTE: Before installation, the config.json file must be edited if the end user is not always required to use Multi-Factor Authentication for logging on a local console and / or remote console – see the Set end user access level section for access level settings and configuration.

Also in this optional section, find information about enabling Multi-Factor Authentication when using SSH for remote login access to a Mac.

Pre-installation steps 

Optional: Set end user access level

Login for Mac by default requires the end user to use Multi-Factor Authentication to access the local console and a remote console in an SSH session.

Before installing Login for Mac on the end user's (target) machine, the config.json file must be edited if you wish to change the end user's login access level setting.

Change the user's access level

1. Find the config.json file which you downloaded in step 19 of the Web Admin Configuration section of this document, and copy that file to the Temp folder on the target machine.

2. Start a text editor such as Sublime Text and edit the access_level in the file, changing the value to a pertinent value:

  • 0 = Multi-Factor Authentication always required
  • 1 = Multi-Factor Authentication required for local access only
  • 2 = Multi-Factor Authentication required for remote access only
  • 3 = Multi-Factor Authentication never required – this setting is used for Self-service Password Reset (SSPR) only

3. Save the configuration.

Optional: Enable and use Multi-Factor Authentication for Remote Access (SSH)

1. On the Mac, go to Settings, select Sharing, and then enable Remote Login.

2. After making this setting, SSH into the machine via ssh username@hostname – example: ssh jsmith@170.17.0.150

3. Enter your password, and you will be prompted for Multi-Factor Authentication.

Verify "allow_self_signed" setting

Find the config.json file you downloaded in step 19 of the Web Admin Configuration section of this document, and verify the setting for "allow_self_signed". You may need to change this setting based on how users will log on your environment.

Setting "allow_self_signed" to True is commonly used in test or lab environments in which the server has a self-signed certificate. This setting is notsupported in a production environment since it introduces critical security risks, namely the potential "Man in the middle" attack which grants users access to a system without validating their credentials, and lets unauthorized users steal OATH seeds.

Note that once installing an endpoint with "allow_self_signed" set to True, this setting remains effective until Login for Endpoints is uninstalled and then re-installed using a configuration file with "allow_self_signed" set to False. 


Installation steps

Do not install Login for Mac version 1.0 on any MacOS Sierra machine (10.12.x) in a domain-joined system on which FileVault encryption is used on the boot volume – this may render the operating system unbootable and require recovery. 

Copy the JSON file to a specified folder

1. Find the config.json file which you downloaded in step 19 of the Web Admin Configuration section of this document.

NOTE: You may have already performed this step if you changed the user's access level in the Set end user access level section above.

2. Copy that file to a specified folder on the target machine.

Download the Login for Mac ZIP file to the specified folder

1. Download the Login for Mac .zip file to the target machine.

2. Unzip this file which contains the SecureAuthLogin-1.x.pkg and SecureAuthLogin-1.x-Uninstaller.pkg files.

3. Copy these files to the same folder as the config.json file on the target machine.

Run the Login for Mac installer package

1. Double-click SecureAuthLogin-1.x.pkg to start the installation wizard for the application.

2. Log Out of the target machine.

NOTE: After this installation, SecureAuth Login for Mac appears on the next login session.


End user login experience 

IMPORTANT

  • The enterprise WiFi connection must be disabled on the Mac in order to log on to the domain. A public WiFi connection or a wired connection can be used for Internet access.
  • If you are included in a bypass group, you should patiently wait for the network group to be fully connected before logging on.

First-time login experience

1. Enter your domain username and password on the Mac login screen.

When using Login for Mac for the first time, you must supply a timed passcode from either the SecureAuth Authenticate App on your mobile device or another device provisioned with the SecureAuth IdP realm to supply timed passcodes, such as a YubiKey. This window (pictured below) only appears the first time you use Login for Mac.

Optionally, check the Remember my selection box if you want to use this same authentication method the next time you log on the Mac.

2. Enter the passcode that appears on the device, and then click Submit.

NOTE: After successfully logging on the Mac using a timed passcode, timed passcodes from that device can be used for login access in the offline mode, i.e. when the Mac is not connected to the Internet.

3. Log Out of the Mac.

4. Log back on the Mac, and select an authentication option from the list of Multi-Factor Authentication methods for which you have previously enrolled.

NOTE: If your list of available authentication options is lengthy, you may need to scroll down the list if the option you wish to choose does not appear on the main page.

5. Optionally, check the Remember my selection box if you want to use this same authentication method the next time you log on the Mac.

6. Click Submit to access the Mac on the network.

NOTE: Authentication method workflows are described in the sub-sections below.

No matter which option you choose, you can return to this selection window by clicking the link: I want to choose a different two-factor authentication method.

SecureAuth Authenticate Mobile App options

Receive passcode from notification

When selecting this option, the Enter Passcode window appears.

1. Enter the passcode that was sent to the SecureAuth Authenticate App on your mobile device.

2. Click Submit to log on the Mac.

Approve login notification

When selecting this option, the Waiting for Your Approval window appears.

1. Accept the login notification sent to the SecureAuth Authenticate App on your mobile device to log on the Mac.

Enter timed passcode from app

When selecting this option, the Enter Passcode window appears.

1. Enter the OATH OTP from your SecureAuth OTP App.

2. Click Submit to log on the Mac.

SMS / Text Message

Receive passcode

When selecting this option, the Enter Passcode window appears.

1. Enter the passcode sent via SMS to your mobile phone.

2. Click Submit to log on the Mac.

Email

Receive passcode

When selecting this option, the Enter Passcode window appears.

1. Enter the passcode sent to your email address.

2. Click Submit to log on the Mac.

Voice Call

Receive passcode

When selecting this option, the Enter Passcode window appears.

1. Enter the passcode sent to your email address.

2. Click Submit to log on the Mac.

Additional Methods options

Contact the help desk

When selecting this option, the Enter Passcode window appears.

1. Input the passcode supplied by the help desk.

2. Click Submit to log on the Mac.

Enter passcode - HOTP Device

When selecting this option, the Enter Passcode window appears.

1. With the YubiKey HOTP device inserted in the machine, tap / press the device to populate the passcode in the field.

2. Click Submit to log on the Mac.

Release notes 


Version 1.0.3 - Release Date: September 17, 2018

New features

CP-230Adaptive Authentication can now be used with Login for Mac.
CP-459A warning message now appears to end users if the 'allow_self_signed' flag is enabled in config.json.

Enhancements

CP-358The Two-Factor Authentication Method screen now informs a user that more options are available, if not all options currently appear on the screen.
CP-452The Login for Mac first login experience now matches the first-time login experience for Login for Windows users.

Known issues

CP-288Login for Mac performance degradation when loading the login screen in the offline mode on High Sierra.
CP-303Login for Mac becomes unsynchronized with SecureAuth IdP and shows an empty screen after Mac comes out of sleep mode.
CP-346Bypass groups are only enforced when a system is online and can check group membership.
CP-386SMS / Voice telephone numbers are not completely masked for registered Multi-Factor Authentication methods.
Version 1.0.2 - Release Date: June 13, 2018

Resolved issues and enhancements

CP-309Login for Mac .pkg files have been renamed for consistency with Login for Windows .msi file names.
CP-317Login for Mac now validates the configuration file correctly.
CP-327The initial Multi-Factor Authentication method window now shows a selected option.
CP-359The installation failure log (Command+L) now identifies a missing configuration file.
CP-379Log details have been added to help troubleshoot common installation errors.
CP-398The installer error message for a missing configuration file has been revised for clarification.
CP-390Users are no longer locked out on Sierra 10.12.x machines with a FileVault encrypted drive.
CP-392Device names receiving push requests now appear on Login for Mac waiting screens.

Known issues

CP-346Bypass groups are only enforced when a system is online and can check group membership.
CP-386SMS / Voice telephone numbers are not completely masked for registered Multi-Factor Authentication methods.
Version 1.0.1 - Release Date: May 14, 2018

Known issues

  • Login failure for users with a space in sAMAccountName

The issue for users who are unable to log in if a space exists in their sAMAccountName property cannot be resolved because macOS does not support using spaces in login names.

  • Critical issue with FileVault on Sierra

Do not install Login for Mac 1.0 on MacOS 'Sierra' (10.12.x) in a domain-joined system that uses FileVault encryption on the boot volume; this may render the system unbootable and require recovery.

  • SMS and Voice numbers are not correctly masked

Users prompted for Multi-Factor Authentication can view the full telephone number for a registered Multi-Factor Authentication method.

  • Additional Authentication methods may be hidden

Since many MacOS configurations do not display a scrollbar, users who are prompted to select an authentication method may not know there are additional methods available to them if they do not see them on the screen currently displayed.

  • Multi-Factor Authentication only prompts users at login

Login for Mac does not currently support prompting users for additional factors when unlocking the screen of an already logged-in user.

  • Offline login may not complete

Users attempting to login offline for a second time using a TOTP code (after logging on and logging off) may have their machine after entering the code.

  • Login for Mac will install on unsupported MacOS versions

Login for Mac is only supported and tested on MacOS versions 10.12.x (Sierra) and 10.13.x (High Sierra), but currently the installer allows installation to proceed on versions 10.10.x and 10.11.x.


Version 1.0 - Release Date: February 1, 2018

The new Login for Mac product gives end users a secure login experience on a Mac workstation using a SecureAuth Multi-Factor Authentication method. This product, with FIPS 140-2 compliant cryptographic libraries, is newly designed and engineered and replaces the Credential Provider application. After the initial setup and first-time usage, the end user subsequently logs on without a password by using only a two-factor authentication method. 


Related documentation

YubiKey HOTP Device Provisioning and Multi-Factor Authentication Guide

SecureAuth Credential Provider Configuration Guide

Login for Windows configuration guide v1.0.3

Login for Endpoints Configuration Guide v1.0.2



  • No labels