--- title: Installing the PingID integration for Mac login description: You can install the PingID integration for Mac login with the UI wizard or with the command-line installation. component: pingid page_id: pingid:pingid_integrations:pid_installing_integration_for_mac_login canonical_url: http://docs.pingidentity.com/pingid/pingid_integrations/pid_installing_integration_for_mac_login.html revdate: January 23, 2024 section_ids: installing-pingid-integration-for-mac-login-using-ui-wizard: Installing PingID integration for Mac login using UI wizard before-you-begin: Before you begin about-this-task: About this task steps: Steps result: Result: result-2: Result: result-3: Result: result-4: Result: result-5: Result: result-6: Result: result-7: Result: result-8: Result: result-9: Result: installing-pingid-integration-for-mac-login-using-cli: Installing PingID integration for Mac login using CLI before-you-begin-2: Before you begin about-this-task-2: About this task steps-2: Steps result-10: Result: choose-from: Choose from: mac-login-command-line-reference: Mac login command line reference --- # Installing the PingID integration for Mac login You can install the PingID integration for Mac login with the UI wizard or with the command-line installation. | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | If for some reason you decide to downgrade to an earlier version of the PingID integration with Mac login, you must completely remove the installed version and only then install the earlier version. | * UI * CLI * CLI reference ## Installing PingID integration for Mac login using UI wizard Install PingID integration for Mac login through the user interface (UI). ### Before you begin | | | | - | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | Adding any multi-factor authentication (MFA) *(tooltip: \
\

An electronic authentication method where a user is granted access only after presenting two or more verification factors for authentication.\

\
)* is a procedure that carries the risk of being locked out of the machine.- Several verifications are done on the parameters supplied for the installation to minimize any locking. The PingID integration for Mac login permits recovery from a lockout scenario by restarting the machine in **Single User Mode**. - Ensure that the **remote login** option is enabled on the Mac to allow connection to the machine by Secure Shell (SSH) *(tooltip: \
\

Protocol for secure operation of network services over an unsecured network.\

\
)*. | To install the PingID integration, you must have: * Administrator privileges on the target Mac machine. * A copy of the organization's `pingid.properties` file. For instructions on how to download the relevant PingID properties file (with full or restricted permissions), see [Managing the PingID properties file](pid_managing_pid_properties_file.html). ### About this task To install the PingID integration for Mac login using the UI wizard: ### Steps 1. On the [PingID Downloads](https://www.pingidentity.com/en/resources/downloads/pingid.html) page, go to **Integrations** and download the PingID package `.pkg` file for Mac login. 2. Double-click the `PingID-MacOS-Login.dmg` file to launch the setup wizard. #### Result: The installer opens. ![A screen capture of the Ping ID for Mac login - initial screen.](_images/tev1676208794426.png) 3. Double-click the **PingID.pkg** icon. 4. At the security check window, click **Continue**. 5. At the installer commencement window, click **Continue**. #### Result: The Software License Agreement window is displayed. 6. Review the Software License Agreement, click **Continue**, and when prompted, click **Agree**. #### Result: The installation proper starts with the **Installation Type** window. ![A screen capture of the Mac login installation - select installation type.](_images/oom1598272520520.png) 7. **Optional:** Click **Change Install Location**. #### Result: The **Destination Select** window opens. ![A screen capture of the Mac login installation - select destination.](_images/ttu1598272664569.png) 8. Keep the highlighted option unless there are compelling reasons for a different choice. Click **Continue** and then click **Install**. 9. If required, enter your machine user name and password. #### Result: You see the following caution message. ![A screen capture of the Mac login installation - installation confirmation message.](_images/jsg1598272774600.png) 10. Click **Continue Installation**. 11. In the **Organization Information** pane, click **Browse**, and then select the `pingid.properties` file that you downloaded from the Admin portal. For more information, see [Managing the PingID properties file for Windows and Mac login](pid_windows_and_mac_login.html). ![A screen capture of the Mac login installation - Organization information page.](_images/ctm1598272876352.png) 12. Click **Continue**. #### Result: The **Manual Authentication** window opens. ![A screen capture of the Mac login - manual authentication options.](_images/mnh1653828600107.png) Choose the option to use for situations where the user cannot communicate with the PingID server: * Required: User can use the PingID mobile app for offline access. If they do not have a paired mobile device, their access is blocked. * Optional: User must use the PingID mobile app for offline access, but if they don't have a paired mobile device, MFA is bypassed. * Disabled: Offline access is not permitted. 13. Click **Continue**. #### Result: The **The Domain / Username Mapping** window is displayed. ![Mac login installation - username mapping](_images/xmz1690962504046.png) 14. In the **Domain / Username Mapping** window, select **Specific username mapping** and choose one of the available Active Directory attributes to use for identifying users, or select the **Legacy username parsing convention** option. If you select **Legacy username parsing convention**, you can optionally provide the organization domain so that users can provide just their user name when logging in, for example, `john.smith`, rather than entering user name plus domain name, such as `john.smith@somewhere.com`. The domain format should be: * `@domainname`, such as `@somewhere.com` * Maximum of 50 characters * The string entered in this field is appended to the username during sign on By default, domain validation is carried out for the domain that you specify in the **Organization Domain** field. You can use the **Skip domain validation** option to specify that PingID should skip domain validation. | | | | - | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | Because the username (plus domain name if set here) is sent to PingID for second factor authentication, it must precisely match a username entered through the admin portal. For PingID, user `john.smith` is not the same as `johm.smith@somewhere.com` even if the domain is correct. | 15. Click **Continue**. If you changed anything in the previous step, you might be asked to enter your machine username and password. #### Result: When the installation is complete, you see the following window. ![A screen capture of the Mac login installation - installation success message.](_images/nod1598273193260.png) 16. Click **Log Out**. #### Result: You are asked what to do with the installer package. ![A screen capture of the Mac login installation - question about deleting installer package.](_images/jjv1598273445997.png) 17. Decide whether to keep the installer package. The installer exits and the machine is logged out to apply the changes. 18. **Optional:** After successful installation, the downloaded `pingid.properties` file may be deleted from the Mac. 19. To verify the installation, test that a user can sign on to the Mac machine using the PingID integration for Mac login. ## Installing PingID integration for Mac login using CLI Install the PingID integration for Mac login using the command-line interface (CLI). ### Before you begin | | | | - | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | Adding any multi-factor authentication (MFA) is a procedure that carries the risk of being locked out of the machine.- Several verifications are done on the parameters supplied for the installation to minimize any locking. The PingID integration for Mac login permits recovery from a lockout scenario by restarting the machine in **Single User Mode**. - Ensure that the **remote login** option is enabled on the Mac to allow connection to the machine by SSH. | To install the PingID integration, you must have: * Administrator privileges on the target Mac machine. * A copy of the organization's `pingid.properties` file. For instructions on how to download the relevant PingID properties file (with full or restricted permissions), see [Managing the PingID properties file](pid_managing_pid_properties_file.html). ### About this task Installing the PingID integration from the command line is useful for deploying to multiple machines in batch mode. To install the PingID Integration for Mac login using the CLI: ### Steps 1. On the [PingID Downloads](https://www.pingidentity.com/en/resources/downloads/pingid.html) page, go to **Integrations**, and download the PingID package `.pkg` file for Mac login. 2. Double-click the **PingID-MacOS-Login\.dmg** file to launch the setup wizard. #### Result: The installer opens. ![Ping ID for Mac login - initial screen](_images/tev1676208794426.png) 3. Copy and paste the `PingID.pkg` and `InstallPingID` files to a convenient location. 4. Download the PingID properties file to the location in step 3. 5. Open a terminal session and change directory to where you copied the file in step 3. 6. **Optional:** To see the available CLI help, run the `./InstallPingID --help` command. 7. Run the installation from a command prompt or create a script containing the required install command. #### Choose from: * Install using the `pingid.propertie`s file to supply parameter values. `./InstallPingID --orgSettingsFilePath /Users/admin/Downloads/pingid.properties [optional parameters]` * Install without using the `pingid.properties` file. Supply the `--orgAlias`, `--orgKey`, `--authenticatorAddress`, `--idpUrl`, and `--token parameter` values on the command line. `./InstallPingID --orgAlias --orgKey --authenticatorAddress --idpUrl --token [optional parameters]` ## Mac login command line reference The following tables provide an overview of the command line commands you can use for the PingID integration for Mac login \== Running the installer from the CLI The general command line is `./InstallPingID [options] [filepath_opt]` Where: `[filepath_opt]` takes the form `-p ` or `--package `. **PingID properties** | Parameter\ | Description | | ------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `-f, --orgSettingsFilePath ` | The full file path of the PingID properties file. For example, `/Users/admin/Downloads/pingid.properties`.The PingID properties file is referenced from this location during the installation process.You must specify either:- `-f, --orgSettingsFilePath`OR all of the following parameters:- `-a, --orgAlias` - `-k, --orgKey` - `-u, --authenticatorAddress` - `--idpUrl` - `-t, --token` If any of the above parameters are specified, and /orgSettingsFilePath is also specified on the command line, then the values are retrieved from the pingid.properties file only, and the values of these other parameters specified on the command line are ignored. | | `-a, --orgAlias ` | The organization's alias. This value is an entry in the PingID properties file.If the `--orgSettingsFilePath` parameter is not specified, it is mandatory to provide the `--orgAlias` parameter.If both the `--orgSettingsFilePath` and `--orgAlias` are specified, the value is retrieved from the`pingid.properties` file, and the value of the `--orgAlias` parameter is ignored. | | `-k, --orgKey ` | The organization's base64 key. This value is an entry in the PingID properties file.If the `--orgSettingsFilePath` parameter is not specified, it is mandatory to provide the `--orgKey` parameter.If both the `--orgSettingsFilePath` and `--orgKey` are specified, the value is retrieved from the`pingid.properties` file, and the value of the` --orgKey` parameter is ignored. | | `-u, --authenticatorAddress ` | The URL of the PingID data center to which the organization is associated.It is the URL that is listed on the line in the `pingid.properties` file that begins with` authenticator_url=`.If the `--orgSettingsFilePath` parameter is not specified, it is mandatory to provide the `--authenticatorAddress` parameter.If both the `--orgSettingsFilePath` and `--authenticatorAddress` are specified, the value is retrieved from the `pingid.properties` file, and the value of the `--authenticatorAddress` parameter is ignored. | | `--idpUrl ` | The URL of the server used for PingID API requests.Take this value from the`idp_url` entry in the `pingid.properties` file.If the `--orgSettingsFilePath` parameter is not specified, you must provide the `--idpUrl` parameter.If both the `--orgSettingsFilePath` and `--idpUrl` parameters are specified, the value is retrieved from the `pingid.properties` file, and the value of the `--idpUrl` parameter is ignored. | | `-t, --token ` | The identifier of the API key. This value is an entry in the PingID properties file.If the `--authenticatorAddress` parameter is not specified, it is mandatory to provide the `--token` parameter.If both the `--orgSettingsFilePath` and `--token` are specified, the value is retrieved from the `pingid.properties` file, and the value of the `--token` parameter is ignored. | | `--usernameMapping ` | Use the `usernameMapping` parameter if you want to use an Active Directory attribute to identify users. Use one of the following values:- `UPN` - use the *userPrincipalName* attribute - `SAM` - use the *SamAccountName* attribute - `SID` - use the *objectSid* attribute - `None` - use the legacy username parsing convention`None` is the default value, so if you do not include the `usernameMapping` parameter, the legacy username parsing convention will be used. | | `--excludeLocalAccounts ` | Use the `excludeLocalAccounts` parameter to control whether PingID authentication should be applied to local user logins.- 0 - Use PingID authentication for local user logins as well - 1 - Do not use PingID authentication for local user logins | | `-i, --ignoreConnectionErrors` | The installer attempts to address the PingID authenticator heartbeat to confirm connectivity. If there is no response before installing any of the elements, continue the installation. | | `-s, --silent` | The installer will prompt with a **Log out now?** message box. | | `-m, --very-silent` | The installer will sign out without asking. | **Domain** | Parameter\ | Description | | ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `-d, --domainPostfix <@organization domain name>` | Configures the installation to append the value supplied in this parameter to the username at sign-on time. You can define a suffix, such as @domain.com, but not a prefix, such as domain/. Enter the leading "@" before the domain name, for example --domainPostfix @somewhere.com.This parameter has a maximum length of 50 characters, including the leading "@". | | `--skipDomainValidation` | By default, domain validation is carried out for the domain that you specify with the `--domainPostfix` option. You can use the `--skipDomainValidation` option to specify that PingID should skip domain validation. | **Offline Authentication** | Parameter\ | Description | | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `-o, --offlineAuthType ` | The `--offlineAuthType` parameter specifies whether to allow PingID offline (manual) MFA.Possible values for *\* are:- 0: Allow offline MFA with the PingID mobile app. - 1: If the user does not have a paired PingID mobile app with their account, bypass MFA during login. - 2: Do not allow offline MFA. | | `-r, --rsa_padding ` | By default, OAEP padding is used in the encryption for offline authentication. Use `--rsa_padding none` if you do not want to use OAEP padding for offline authentication. | **HTTP Request Timeout** | Parameter\ | Description | | -------------------- | ------------------------------------------------------------------------------ | | `--timeout ` | Defines HTTP request timeout value. Possible values are between 1000-30000 ms. | **Common** | Parameter\ | Description | | -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `-h, --help` | Show a user guide. | | `-v, --version` | Show the Installer version. | | `--allowFullPermissionsPropertiesFile` | If you include the `--allowFullPermissionsPropertiesFile` option during installation, PingID will allow you to use the full-permissions properties file (rather than the restricted-permissions properties file intended for use with Mac login). However, it is strongly recommended that you refrain from doing so. Using the full-permissions properties file with Mac login is a security risk (for details, see [CVE-2022-23717](https://nvd.nist.gov/vuln/detail/CVE-2022-23717)). |