Managing the PingID properties file - PingID

PingID Administration Guide
bundle
pingid
ft:publication_title
PingID Administration Guide
Product_Version_ce
PingID
category
ContentType
Product
Productdocumentation
pingid
ContentType_ce
Product documentation

The various integrations with PingID require information that is stored in the PingID properties file, which can be downloaded from the admin console.

Download the PingID properties file relevant for your platform:

PingFederate

You can download the PingID for PingFederate properties file for use when integrating PingID with PingFederate.

The Integrate with PingFederate Bridge properties file provides full permission to perform enrollment, device management, and authentication actions. You can rotate or revoke generated properties files with minimal downtime.

Note:

For Window login, Mac login, and SSH integrations, you should download the version of the properties file that restricts user permissions to authentication only. For more information, see the relevant tabs on this page.

The PingID properties file contains sensitive information including the secret encryption key. It should only be handled by administrators and should not be distributed more than is necessary.

Warning:

To ensure minimal downtime when rotating a PingID properties file (key rotation), first generate the PingID properties file and link it to the relevant client, and then revoke the old properties file.

  1. In the PingOne admin portal, go to Setup > PingID > Client Integration.
    Screen capture of the PingID Client Integration window showing how to download the PingID properties file
    The Integrate with PingFederate and Other Clients section is displayed, listing any PingID properties files that are already defined.
  2. To generate a new PingID properties file, click + Generate, and then click Save.
    Note:

    You can have a maximum of five active PingID properties files. If you have five active files and want to generate a new one, you must first revoke one of your existing files.

    A new entry is added to the properties file list, showing the new PingID properties file.
  3. In the relevant row, click Download, and then save the file to the desired location with a meaningful name.
  4. To revoke an old PingID properties file:
    1. Download and open the PingID properties file you want to revoke, and ensure the token matches the token listed in the web portal.
    2. In the relevant row of the properties file list, click Revoke, and then click Save.
    The selected file is removed from the PingID server and can no longer be used for authentication.

Windows and Mac login

The Windows and Mac login PingID properties file provides a limited subset of permissions that enable users to perform Windows or Mac login authentication while preventing them from performing management actions, such as enrollment and device management.

The PingID Windows and Mac login properties file contains sensitive information, including the secret encryption key. It should only be handled by administrators and should not be distributed more than is necessary.

Attention:

The outcome of a login attempt by this user can differ if Windows or Mac login was installed with full permissions as opposed to restricted permissions.

Under full permissions, if valid user john.smith creates a new user, joe.blogs, on his Mac and then uses it to login, he is offered a QR code or one-time passcode (OTP) on his registered second factor device and PingID will create a new user named joe.blogs. The full permissions case both registers and provides access to logins. In the restricted permissions case, attempting to log-in as joe.blogs fails with an error message. The restricted permissions case provides access only.

To avoid ad hoc registrations, the admin should always install the login using the restricted permissions properties file.

To download the PingID properties file to integrate with Windows login or Mac login:

  1. In the PingOne admin portal, go to Setup > PingID > Client Integration.

    The Integrate With Windows and Mac Login section is displayed.


    Client Integration tab, Integrate with Windows and Mac login section, showing the options to download, revoke, or generate a PingID properties file with reduced permissions for use with Windows and Mac login.
  2. To generate a new Windows or Mac login PingID properties file, click + Generate, and then click Save.
    Note:

    You can have a maximum of five active PingID properties files. If you have five active files and want to generate a new one, you must first revoke one of your existing files.

    A new entry is added to the Properties file list showing the new PingID properties file.

  3. Select the Enable Device Management option if you want to allow users to manage their devices from their Devices page and allow users to register their device the first time they try to access a resource that requires authentication ("on-the-fly registration"). When this option is selected, these features will be available to any user that uses that copy of the PingID properties file when installing the integration with Windows login.
    Note: To carry out on-the-fly registration of FIDO2 security keys, users must have installed version 2.11 or higher of the integration with Windows login.
  4. In the relevant row, click Download, and then save the file to the desired location using a meaningful name.

SSH

The SSH Properties file provides a limited subset of permissions that enable users to perform authentication while preventing them from performing management actions (such as enrollment and device management).

The PingID SSH Properties file contains sensitive information including the secret encryption key. It should only be handled by administrators, and should not be distributed more than is necessary.

Attention:

The outcome of a login attempt by this user can differ if SSH was installed with full permissions as against restricted permissions.

Under full permissions, if valid user john.smith creates a new user, joe.blogs, on his Mac and then uses it to login, he will be offered a QR code or OTP on his registered second factor device and PingID will create a new user named joe.blogs. The full permissions case both registers and provides access to logins. In the restricted permissions case, attempting to login as joe.blogs will fail with an error message. The restricted permissions case provides access only.

To avoid ad hoc enrollments, the admin should always install SSH using the restricted permissions properties file.

To download the PingID properties file to integrate with SSH:
  1. In the PingOne admin portal, select Setup > PingID > CLIENT INTEGRATION.
    The INTEGRATE WITH SSH area is displayed.

  2. To generate a new SSH PingID properties file, click + Generate and then click Save.
    Note:

    You can have a maximum of five active PingID properties files. If you have five active files and want to generate a new one, you must first revoke one of your existing files.

    A new entry is added to the Properties file list showing the new PingID Properties file.
  3. In the relevant row, click Download, and then save the file to the desired location using a meaningful name.

Rotating and revoking a PingID properties file

You can rotate or revoke a PingID properties file.

Revoking a properties file removes it from PingID, invalidating any devices that used it.

CAUTION:

Revoking a properties file should be done with extreme caution. Users signed on to machines with authentication based on a revoked properties file can continue to work normally. However, at their next sign on, they won't be able to authenticate and will be locked out of their machines.

Rotating a properties file involves replacing a properties file with a new one. To minimize downtime to users:

  1. In the PingOne admin portal, go to Setup > PingID > Client Integration.

    The Client Integration page shows all PingID properties files associated with each type of properties file, such as PingFederate and unrestricted, Windows and Mac login, or SSH login properties files.


    Screen capture of the Client Integration tab showing an example of an existing PingID properties file.
  2. To ensure minimal downtime when rotating a PingID properties file (key rotation):
    1. To generate a new PingID properties file, click + Generate.
    2. The Download button next to the name of the generated file is displayed as disabled. Click Save at the bottom of the page to enable the Download button.
    3. Click Download.
    4. Link it to the relevant client.

      The documentation for each client explains how it is linked, such as by running the GUI or CLI installer.

  3. In the properties file list, select the file to be revoked (the old properties file from step 2, if relevant) and click Revoke.

    A confirmation window is displayed.


    Screen capture of the Revoke File confirmation window, warning that if you continue and revoke the properties file, any client using the properties file will lose their access. It shows the Revoke button to confirm or the Cancel button to cancel the action.
  4. Click Revoke, and then click Save.
    The selected file is removed from the PingID server and can no longer be used for authentication.