Enterprise Connect

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.