Enterprise Connect

Mac Workstation Authentication

Mac Workstation Authentication provides your organization with the capability to secure Mac workstations or servers with rich multi-factor authentication (MFA) using:

  • Push notifications through the ForgeRock Authenticator application.

  • OATH one-time passcodes (HOTP or TOTP) through the ForgeRock Authenticator application.

Benefits of Mac Workstation Authentication:

  • Provides the fastest and safest way to close the desktop security gap. The first desktop MFA solution to integrate fully with the ForgeRock directory and ForgeRock Authenticator application.

  • Offers unprecedented endpoint security using the familiar ForgeRock Authenticator application. The solution offers end users the best MFA experience while relieving IT teams from the expensive and cumbersome deployment of OTP tokens and security keys to protect workstations.

  • A plug-and-play solution that is easy to install on employee endpoints. No dedicated server is required, enabling fast deployment for the entire workforce. Your organization can now dramatically boost their domain security, improve user experience, and take the first step toward becoming fully passwordless in the future.

Mac Workstation Authentication installation/configuration checklist

  • Download and install the binaries from Backstage (you must be logged in).

  • Install the Mac client on end users machines.

  • (Optional). Onboard and enable local users on their Mac machine.

  • (Optional). Enable Offline OTP to allow users to login to their Mac when not connected to the internet.

  • Verify and test with a test user.

Prerequisites

Before beginning installation, verify that:

  • You decide if the Macs will be domain-joined or standalone. Mac Workstation Authentication supports both.

  • You establish connectivity between the ForgeRock environment and the end user’s Mac workstations.

    Communication with the ForgeRock environment is crucial for Mac Workstation Authentication to function properly. Adjust your network settings appropriately.

  • To support the MFA methods in Mac Workstation Authentication, end users must download the ForgeRock Authenticator application to their smartphone via the Apple store or Google Play store.

  • For push or OATH TOTP MFA methods to work, you must pre-configure the journey.

  • You have administrative permissions in the ForgeRock environment.

  • Download and install the binaries from Backstage (you must be logged in).

  • The Mac configuration XML file is ready to be deployed.

Supported environments

Mac Workstation Authentication can only be installed on the following operating systems:

  • macOS Sonoma

  • macOS Ventura

  • macOS Monterey

Mac Workstation Authentication supports both Intel x86-64 and Mac M1/M2/M3 architecture.

Install Mac Workstation Authentication

There are three steps to install the Mac Workstation Authentication:

  1. Prepare for installation

  2. Install the Mac Workstation Authentication

  3. Onboard local users

Prepare for installation

To install the Mac Workstation Authentication, there are two files provided in the download that are required:

  • WorkstationAuthenticationForMac.pkg: The Mac installer file.

  • WorkstationAuthenticationForMac.xml: The configuration file for the installation.

For successful installation, you must store these files in the same folder and have the same name (with the file type differing).

In Mac Workstation Authentication there are two options for MFA:

  • Push notifications using the ForgeRock Authenticator application.

  • An OATH OTP provided by the ForgeRock Authenticator application.

You can only configure one of the MFA methods to use with Mac Workstation Authentication.

Configure the XML file

Before you can install Mac Workstation Authentication, you must configure the XML file. The XML file includes details about your ForgeRock environment.

To configure the XML file:

  1. Open WorkstationAuthenticationForMac.xml.

  2. At a minimum, fill out the required fields server, realm, and tree.

  3. Save the file.

Parameters in the XML file
Parameter Description

server

Required. Enter the URL of your ForgeRock authentication server.

For example, https://test.forgerock.com/am.

You must include the path to AM in the URL.

realm

Required. Enter the name of the ForgeRock realm to authenticate to.

For example, alpha.

There is no leading / when defining the realm for Mac Workstation Authentication.

tree

Required. The preconfigured journey to use for Mac Workstation Authentication For example, mac-otp.

For examples on the journeys, refer to create push or journey or create an OTP journey.

otpdigits

Optional. This field is relevant only when you want your users to use the OTP MFA method.

If you enter anything in this field, then the OTP method will be configured for your users. Leaving this blank assumes the MFA push notification method is used.

This is the number of digits in the OTP verification code. A value is required in order to successfully use the OTP journey.

You must configure the appropriate journey to use this method.

Ensure that the number you put here matches the number you configure in the One Time Password Length field of the OATH Registration node. You use this node when your end users preregister. For more information, refer to Prerequisites.

credentials

Optional. Determines whether user credentials are sent to ForgeRock.

You must configure the journey to support the validation of the user credentials.

To enable sending credentials, the value should be true.

To disable the sending of credentials, set the value to false.

ssourl

Optional. The URL of the journey that checks for a session and redirects the user, after successfully logging in to their Mac, to an end user portal. By default, this parameter is empty and no browser opens after login.

For example, the URL to the journey could be https://test.forgerock.com/enduser/am/XUI/?realm=alpha&authIndexType=service&authIndexValue=wks-sso&ForceAuth=true.

The Success URL node in that journey could be https://test.forgerock.com/enduser/?realm=alpha#/dashboard.

For an example of this journey, refer to the SSO journey.

ssobrowser

Optional. Determines the browser that opens when the ssourl parameter is defined.

Select one of the following values:

  • system: Uses the default browser configured on the machine.

  • firefox

  • safari

  • chrome

Configure the ssourl and ssobrowser parameters if you want an SSO portal to automatically open on the end users machine upon login.

An example of the XML file completed is:

<?xml version="1.0" encoding="UTF-8"?>
<octopus>

    <!-- ********************************************************************************** -->
    <!-- ***  REQUIRED                                                                  *** -->
    <!-- ********************************************************************************** -->

    <server>https://test.forgerock.com/am</server>
    <realm>alpha</realm>
    <tree>wks-push</tree>
    <otpdigits></otpdigits>
    <credentials>true</credentials>


    <!-- ********************************************************************************** -->
    <!-- ***  OTHERS                                                                    *** -->
    <!-- ********************************************************************************** -->
    <!--
        Logging (default: 'info')

        Controls the number and verbosity of logging messages written by Octopus for Mac.

        The valid values for this setting are (in order of increasing verbosity):
            * none
            * error
            * info
            * debug

        Note that no passwords, encryption keys or any other secrets are ever written in
        any of the above logging levels.
    -->
    <logging>info</logging>


    <!-- ********************************************************************************** -->
    <!-- ***  SINGLE SIGN ON                                                            *** -->
    <!-- ********************************************************************************** -->

    <ssourl>https://test.forgerock.com/am/XUI/?realm=alpha&amp;authIndexType=service&amp;authIndexValue=wks-sso&amp;ForceAuth=true</ssourl>
    <ssobrowser>safari</ssobrowser>

</octopus>

Install Mac Workstation Authentication

Once you configure the XML file, the Mac Workstation Authentication is ready for installation.

To install the client on your user’s workstation, utilize the following options:

  • As an administrator, manually install the client on the machine.

  • Utilize a deployment tool for Macs, such as Jamf. This method is recommended for large deployments.

The steps that follow explore the manual configuration of Mac Workstation Authentication on a machine. When using a deployment tool, adjust the steps and settings accordingly.

To install Mac Workstation Authentication:

  1. As an Administrator, run the WorkstationAuthenticationForMac.pkg file to open the installer.

  2. On the Introduction page, click Continue.

  3. On the Installation Type page, click Install.

    You might be prompted to enter credentials.

  4. Click Ok to allow the software to access the required locations. You are prompted to do this twice.

  5. A pop-up screen to enable Mac Workstation Authentication for the logged-in user appears. To configure this now, click Enable Workstation Authentication. For more information, refer to Onboard local users.

    To set up later for yourself (or another user), click Not Now.

  6. Click Close to exit the installation setup.

  7. Verify the installation by locating the ForgeRock icon in the top right of the menu bar. This shows that the Mac Workstation Authentication is running in the background.

    To access Mac Workstation Authentication settings at any time, click the logo and click Open Workstation Authentication Preferences…​.

    client install verify fr icon
After you enable Mac Workstation Authentication, the end user is prompted to set up Mac Workstation Authentication when logging into their machine.
Mac Workstation Authentication installation/configuration checklist

  • Download and install the binaries from Backstage (you must be logged in).

  • Install the Mac client on end users machines.

  • (Optional). Onboard and enable local users on their Mac machine.

  • (Optional). Enable Offline OTP to allow users to login to their Mac when not connected to the internet.

  • Verify and test with a test user.

Onboard local users

If there are local (non-domain) users, for example, users not in AD, then those users must be manually enabled before they can log into their workstation using Mac Workstation Authentication.

To onboard a local user:

  1. Log into the Mac as a local user.

  2. Click the ForgeRock icon in the top right of the menu bar.

  3. Click Enable For This User…​.

  4. Enter the user’s username in the Account field and click Next.

  5. Enter the user’s Mac credentials.

    1. If you are using the push MFA method, after you validate the Mac credentials, a notification is sent to the ForgeRock Authenticator application to approve.

    2. If you are using the OATH OTP MFA method, put the OTP code from the ForgeRock Authenticator application right after the password in this step.

      Failure to do this will result in the end user not being registered.

Mac Workstation Authentication installation/configuration checklist

  • Download and install the binaries from Backstage (you must be logged in).

  • Install the Mac client on end users machines.

  • (Optional). Onboard and enable local users on their Mac machine.

  • (Optional). Enable Offline OTP to allow users to login to their Mac when not connected to the internet.

  • Verify and test with a test user.

Enable Offline OTP

Offline OTP is performed by the user.

After a user is configured to use Mac Workstation Authentication, the user can enable Offline OTP.

This option provides the ability to for users to authenticate to their Mac when they are not connected to a network or their machine cannot access the ForgeRock environment.

Users must download the ForgeRock Authenticator application to their smartphone via the Apple store or Google Play store to set up Offline OTP.

To enable Offline OTP:

  1. Click the ForgeRock icon in the top right of the menu bar and click Open Workstation Authentication Preferences…​.

    You can also access the Workstation Authentication application by opening it in Finder.

  2. From the Mac Workstation Authentication application screen, click Manage to launch the offline login wizard.

  3. After the wizard opens, click Setup.

  4. When prompted, enter your password in the dialog.

    1. If the push notification MFA method has been set up, approve the push notification on your phone.

    2. If the OATH OTP MFA method was set up, append the OTP to the end of your password with no spaces in between.

  5. Scan the QR code that is presented on the screen with you ForgeRock Authenticator application.

  6. Enter the OTP from the newly created profile in your ForgeRock Authenticator application to the screen titled Verify Your Code. Note the name of the profile in the application for later reference.

  7. To exit the wizard, click Done.

Login with Offline OTP

After you enable and configure Offline OTP, you are ready to log in using this method.

To login using the Offline OTP MFA method:

  1. Enter your password to your Mac.

  2. In the password box (right after you enter the password with no space in between the password and OTP) enter the OTP from the ForgeRock Authenticator application.

  3. Press Enter.

Mac Workstation Authentication installation/configuration checklist

  • Download and install the binaries from Backstage (you must be logged in).

  • Install the Mac client on end users machines.

  • (Optional). Onboard and enable local users on their Mac machine.

  • (Optional). Enable Offline OTP to allow users to login to their Mac when not connected to the internet.

  • Verify and test with a test user.

Verify functionality

Following installation, configuration, and deployment (on a test machine first), it is recommended to test the functionality of workstation authentication to verify that the Mac login process proceeds as expected.

Before beginning the verification process, make sure that the following prerequisites are met:

  • User to be tested has a smartphone with the ForgeRock Authenticator application installed.

  • User to be tested has been successfully enrolled to the relevant journey depending on the method chosen (push notification or OATH OTP) as described in Install Mac Workstation Authentication.

  • The ForgeRock Server URL, as defined in the xml file, is accessible from the test machine.

  • Mac Workstation Authentication has been enabled for the account on the Mac machine.

There are two MFA methods an administrator can enable for Mac Workstation Authentication. Only one can be selected.

The methods are:

  • Push notification using the ForgeRock Authenticator application

  • OATH OTP using the ForgeRock Authenticator application

Offline OTP can also be enabled for either of these methods. For more information on this, refer to Enable Offline OTP.

The following sections show how to test these methods.

Validate push notification MFA method

You configure the push notification MFA method when you Install Mac Workstation Authentication.

To log in to your Mac with this method:

Display an example
verify mac auth push notification

  1. Access the Mac login screen.

  2. Enter the username and password for the user.

  3. Approve the push notification sent to the ForgeRock Authenticator application.

  4. You are successfully logged in.

Validate OATH OTP MFA method

You configure the OATH OTP MFA method when you Install Mac Workstation Authentication.

To log in to your Mac with this method:

Display an example
verify mac auth oath otp notification

  1. Access the Mac login screen.

  2. Enter the username and password for the user.

  3. Right after you enter the password, input the OTP from the application immediately (with no spaces in between).

  4. You are successfully logged in.

Mac Workstation Authentication installation/configuration checklist

  • Download and install the binaries from Backstage (you must be logged in).

  • Install the Mac client on end users machines.

  • (Optional). Onboard and enable local users on their Mac machine.

  • (Optional). Enable Offline OTP to allow users to login to their Mac when not connected to the internet.

  • Verify and test with a test user.

Additional reference

The subsequent sections explore additional features of Mac Workstation Authentication:

Perform Mac Workstation Authentication upgrade

When substantial updates are released in a newer version of Mac Workstation Authentication, you need to upgrade.

Upgrade Mac Workstation Authentication

When you upgrade Mac Workstation Authentication, run the .pkg file over the existing installation. Do not uninstall the older version as this would require end users to re-enable Mac Workstation Authentication.

  1. Download the binary from Backstage to the machine(s) that require an upgrade.

  2. Configure the XML file for the new version as described in configure the XML file.

  3. Install the new version as described in install Mac Workstation Authentication.

For larger deployments, utilize a deployment tool, such as Jamf to upgrade.

Log files

Mac Workstation Authentication logs various items, such as installation activities and authentication events.

To access the log file:

  1. Click the ForgeRock icon in the top right of the menu bar and click Open Workstation Authentication Preferences…​.

    You can also access the Workstation Authentication application by opening it in Finder.

  2. Click Help.

  3. In the Troubleshooting section, click View logs.

You can also access the log file directly via the terminal at /var/log/octopus.log.

Modify Mac Workstation Authentication

After you install and configure Mac Workstation Authentication, there are many cases in which you will need to modify the configuration.

These items include:

Modify configuration files post installation

When Mac Workstation Authentication is installed, configurations are set at the system level, and when user(s) enable Mac Workstation Authentication on their account, at the user level. Do not modify the configurations after the installation.

If you need to modify the xml file for Mac Workstation Authentication, run the .pkg file over the existing installation. Do not uninstall Mac Workstation Authentication as this would require the end users to re-enable Mac Workstation Authentication.

Instead, install Mac Workstation Authentication over the existing installation:

  1. Configure the xml file.

  2. Reinstall Mac Workstation Authentication following the steps in Install Mac Workstation Authentication.

For larger deployments, utilize a deployment tool, such as Jamf to update the xml file.

Uninstall Mac Workstation Authentication

To uninstall the client:

  1. Click the ForgeRock icon in the top right of the menu bar and click Open Workstation Authentication Preferences…​.

    You can also access the Workstation Authentication application by opening it in Finder.

  2. Click Help.

  3. In the Uninstall section, click Uninstall.

  4. Enter an administrator’s credentials to uninstall.