PingID Administration Guide

PingID RADIUS PCV parameters reference guide

The following tables detail the PingID RADIUS password credential validator (PCV) configuration parameters available in PingFederate.

General Parameters

PingID RADIUS PCV Configuration General Parameters
Parameter Description

RADIUS Clients

Client IP

For the RADIUS Client IP address, use the IP address of the VPN server/remote access system.

Client Shared Secret

The RADIUS client shared secret. The shared secret is shared with the VPN.

Label

Optional: Add a label to a specific client.

Delegate PCVs

Delegate PCV

The instance name of the “LDAP PCV with Extended Attributes” PCV.

If PingID RADIUS PCV is only required to receive user attributes from an LDAP data source, select LDAP as Attribute Source.

This field should be left blank if:

  • The VPN client performs LDAP verification.

  • LDAP verification is not required from the RADIUS PCV.

If RADIUS Remote Network Policy Server mode is enabled, either LDAP as Attribute Source must be selected, or the field should be left blank.

Member Of Groups

Enter one or more pairs of LDAP group attribute and LDAP group name. Users in the groups defined here can be authenticated using PingID MFA. The default value for the LDAP group attribute is memberOf.

Do not enter the full DN. For example, if the full DN is: DN=CN=Android Users,OU=PingGroups,DC=intheory,DC=com enter only the CN value Android Users.

LDAP Group Name for Bypass

Enter one or more LDAP group names. Users in the groups defined here will not be authenticated using PingID MFA.

RADIUS Vendor-Specific Attributes

If you want to have vendor-specific attributes sent during authentication, add them to the RADIUS Vendor-Specific attributes section, and then refer to them when you complete the Multiple attributes mapping rules section.

To add a vendor-specific attribute:

  1. Click Add a new row to 'RADIUS Vendor-Specific attributes'.

  2. Enter the ID of the vendor.

  3. Enter a name for the attribute. Note that this is the field that has to be referred to in the Multiple Attributes Mapping Rules section.

  4. Enter the number of the attribute.

Multiple Attributes Mapping Rules

Permits mapping definitions for LDAP attributes to return all values of the attribute to the RADIUS client or PingID, depending on the Destination Selection. LDAP attributes may contain more than one value (for example, a user may be a member of more than one group), in which case the values are separated by the semicolon (;) character.

  • Single value LDAP attributes may be mapped to either RADIUS client or PingID destination attributes.

  • Multiple value LDAP attributes may be mapped only to RADIUS client destination attributes.

Click Add a new row to 'Multiple attributes mapping rules', and enter the following fields for each rule:

  • Source Selection: LDAP (other values are reserved for future use).

  • Source Attribute: The name of the LDAP attribute whose value will be passed to the RADIUS client or PingID, depending on the value of Destination Selection. The attribute selected here must be included in the extended contract of the Delegate PCV.

  • OGNL Expression: Enter an OGNL expression if you want to fine-tune the mapping between the source and destination attributes. For more information on the use of OGNL expressions for this purpose, see Introduction to OGNL.

  • Destination Selection: RADIUS, Vendor Specific (for vendor-specific RADIUS attributes), or PingID.

  • Destination Attribute: the name of the RADIUS or PingID attribute which will receive the value from the LDAP Source Attribute. For vendor-specific attributes, use the name that you provided in the RADIUS Attribute Name column in the RADIUS Vendor-Specific attributes section of the page.

PingID destination attributes (when the value of Destination Selection is PingID):

  • fname: The attribute containing the user first name. For example, givenName.

  • lname: the name of the LDAP: The attribute containing the user last name. For example, sn.

  • email: The attribute containing the user email address. For example, mail. This email address is used during registration if users need to receive a link on their mobile device to download the PingID application.

  • A PingID Destination Attribute may be mapped to only one LDAP Source Attribute.

  • If the value of one attribute is invalid, the mapping fails for all attributes.

  • RADIUS Attribute Type: The type of the attribute

User Specific Groups to RADIUS Client

Permits mapping specific LDAP user groups in order to send their values to the RADIUS client.

For each group listed in the table:

  • If the user is a member of the group, the LDAP group name (Member Of) is assigned to the RADIUS Attribute.

  • If the user is not a member of the group, the Default Value is assigned to the RADIUS Attribute. If the Default Value is not defined, the RADIUS Attribute will not be sent to the RADIUS client.

Click Add a new row to 'User Specific Groups to RADIUS Client', and enter the following fields:

  • Member Of: The LDAP group name.

  • RADIUS Attribute: the name of the RADIUS attribute which will receive either the LDAP group name from Member Of, or the Default Value, depending on whether the user is a member of the group or not.

  • Default Value: The value to assign to the named RADIUS Attribute when the user is not a member of the LDAP group listed in Member Of. If the Default Value is not defined, the RADIUS Attribute will not be sent to the RADIUS client.

Check Groups

Select this option to initiate PingID authentication only after users are confirmed as members of a group defined in Member of Groups.

When selected, the RADIUS PCV filters groups according to the following configuration fields:

  • LDAP Group Name

  • Fail Login if the User is not Member of the LDAP Group

Check Bypass Groups

Select this option to bypass PingID authentication only after users are confirmed as a member of at least one of the groups defined in the 'Member Of Bypass Groups' section.

If the User is not Activated on PingID

Defines how authentication requests are handled if a user is not registered in the PingID cloud service, or if the user’s mobile device is unpaired. Select either:

  • Register the user (default): Initiate PingID registration for unregistered users and users without a paired mobile device.

  • Always fail the login: Fail authentication requests for unregistered users and users without a paired mobile device.

  • Fail login unless in grace period: If the user is not registered in PingID by the mandatory enrollment date, access is denied.

  • Let the user in without pingid. If the primary authentication (delegate PCV) is successful, allow authentication requests to proceed.

Fail Login on PingID Technical Error

If selected, authentication requests fail if the PingID cloud service is unavailable. When it is not selected, the PingID MFA process is bypassed.

This option is enabled by default.

This field is deprecated in PCV 2.0, and replaced by AUTHENTICATION DURING ERRORS.

Fail Login if the User is not member of the LDAP Group

Select or clear the checkbox.

  • Selected: Authentication fails if the user is not included in any of the groups defined in the LDAP Group Name field.

  • Cleared (default): If a user is not member of any of the groups listed in Member of Groups, authentication will proceed without using PingID.

This option is ignored if Let the user in without PingID is selected.

If no groups are listed in Member of Groups, this field is ignored and authentication requests are performed using both LDAP and PingID authentication.

Enable RADIUS remote network policy server

Enable the RADIUS PCV to work through a Remote Network Policy Server to support MS-CHAPv2 protocols.

RADIUS Network Policy Server IP

The source IP address of the RADIUS endpoint Network Policy Server (NPS) used to validate user credentials.

RADIUS Network Policy Server Port

The port number for the RADIUS endpoint Network Policy Server (NPS) used to validate user credentials.

RADIUS Server Authentication Port

The port number assigned to the PingID PCV RADIUS server. The RADIUS server listens for requests from RADIUS clients on this port. The default value is 1812.

If you are using more than one RADIUS PCV instance in the same PingFederate environment, this value must be unique for each RADIUS PCV instance.

Domain Postfix

A domain name postfix (including ‘@’) that can be appended to the username standardize the PingID usernames throughout the various PingID services (e.g., SSO).

This field is left blank by default.

PingID Properties File

The PingID properties file configures the trusted connection between the RADIUS PCV and the relevant tenant in the PingID service.

From the PingID configuration window, download the PingID properties file and then upload it to the PingID RADIUS PCV instance in PingFederate. For information see Configuring a RADIUS server on PingFederate

To ensure the properties file is encrypted, it must be uploaded to the PingID RADIUS PCV instance in PingFederate.

Authentication During Errors

Determines how to handle user authentication requests when PingID services are unavailable.

  • Bypass User: Accept the user’s first factor authentication, and bypass the PingID MFA flow when the PingID MFA service is unavailable.

  • Block User: Reject and block the user’s login attempt when the PingID MFA service is unavailable.

  • Passive Offline Authentication: Fallback to the PingID offline MFA flow when the PingID MFA service is unavailable. Users will be asked to access MFA offline manual authentication from the PingID mobile app using a mobile device previously registered with PingID, and enter a 12-digit authentication key to obtain an authentication code to authenticate. See also Configuring offline MFA (PingID Adapter).

  • Enforce Offline Authentication: Force PingID offline MFA flow regardless of the PingID MFA service availability.

  • This parameter replaces Fail Login on PingID Technical Error, which is deprecated in PCV 2.0.

Users Without a Paired Device

When PingID services are unavailable, you can choose to bypass or block users who have no paired mobile device (pf-pingid-local-fallback attribute in user’s device list in the user directory).

  • Bypass User indicates users without paired mobile devices will bypass the PingID adapter in an authentication attempt.

  • Block User indicates users without paired mobile devices will have PingID block their authentication attempt.

A user’s individual block or bypass State attribute in the user directory will override the USERS WITHOUT A PAIRED DEVICE definition.

This configuration is only relevant if Passive offline authentication or Enforce offline authentication were chosen in the AUTHENTICATION DURING ERRORS field. See User directory for PingID offline MFA for more details.

LDAP Data Source

The directory data source used to retrieve additional user attributes for offline MFA. This is the data store in which the users device list (pf-pingid-local-fallback attribute) is stored.

If RADIUS Remote Network Policy Server mode is enabled, or if Delegate PCV is defined as LDAP As Attribute Source, all user attributes are retrieved from this directory data source.

Create Entry for Devices

Create the device list entry in the data source if it does not exist. This is the configuration setting for how and when PingFederate will create PingID device entries of type pf-pingid-device.

Applicable only when pf-pingid-local-fallback is added to pf-pingid-device.

  • Checked: PingFederate will create objects of type pf-pingid-device per user, and add the device list information in its pf-pingid-local-fallback attribute.

  • Unchecked: PingFederate will assume that the pf-pingid-device objects per user are being created by an external system, and will only modify the pf-pingid-local-fallback attribute attached to them when needed.

Encryption Key for Devices

This field contains the base64url encoded HMAC256 encryption key to encrypt the users devices list before saving to the user directory. This field is optional. If this field is empty, the devices lists will be kept unencrypted and will be stored as plain text.

  • If the admin changes the encryption key, all users will have to authenticate online at least once, in order for new device details to be kept locally, or else the behavior in an offline scenario will follow the USERS WITHOUT A PAIRED DEVICE setting.

Search Base

The location in the directory from which the LDAP search begins. To be used when the offline authentication attributes are stored on the user entry in the main user LDAP.

Applicable when pf-pingid-local-fallback is added to the user object.

If RADIUS Remote Network Policy Server mode is enabled, or if theDelegate PCV is defined as theLDAP as attribute source, all user attributes are retrieved from this location in data source.

Search Filter

The basis of what to filter, when the device list is stored on the user’s object in the user directory. The Search Filter parameter value must be identical to the Search Base field in the relevant Password Validator Instance Configuration.

You may use ${username} as part of the query. Example (for Active Directory): sAMAccountName=${username}.

  • Applicable only when pf-pingid-local-fallback is added to the user object.

If RADIUS Remote Network Policy Server mode is enabled, or if Delegate PCV is defined as the LDAPAs Attribute Source, all user attributes are retrieved with help of this filter.

Scope of Search

The options for determining the width and depth of the search, when the device list is stored on the user’s object in the user directory:

  • One level: search only in the defined branch, and not in its subtrees.

  • Subtree: search in the defined branch, and all of its subtrees.

  • Applicable only when pf-pingid-local-fallback is added to the user object.

Distinguished Name Pattern

The pattern used to save device entries. It points to the location in the directory in which the pf-pingid-device objects reside.

  • You may use either this DISTIGUISHED NAME PATTERN setting, OR the set of the 3 SEARCH configuration settings (SEARCH BASE, SEARCH FILTER and SCOPE OF SEARCH) above.

  • DISTIGUISHED NAME PATTERN must be used in either of the following scenarios:

    • When using more than one PCV or PingID Adapter instance with more than one configured PingID tenant.

    • When both the PCV and PingID Adapter are configured with more than one tenant.

  • This parameter is required only if offline authentication is enabled when the pf-pingid-local-fallback attribute is saved separately from the user object.

If RADIUS Remote Network Policy Server mode is enabled, or if Delegate PCV is defined as LDAP As Attribute Source, all user attributes are retrieved with the help of this pattern.

State Attribute

The STATE ATTRIBUTE is used to override how a specific user is authenticated during offline authentication. The value of this field is the name of the attribute configured in the directory. If the PingID services are unreachable, the value of STATE ATTRIBUTE is evaluated:

  • Bypass: the user bypasses PingID MFA.

  • Block: (case insensitive), the user will be blocked from performing the PingID offline MFA flow, and denied access.

  • Empty: the user attribute set in the directory won’t be used during offline authentication.

The exact name of the attribute configured in this field must also be added in the Extended Contract tab of the relevant Delegate PCV. This parameter is unrelated to the State Encryption Key parameter in the following table.

Advanced Parameters

PingID RADIUS PCV Configuration - Advanced Parameters
Parameter Description

Server Threads

Enter a number to specify a fixed number of threads that can use a shared unbounded queue to service RADIUS requests.

If no value is specified, new threads are created as required, and previously constructed threads are reused when available.

Threads that have not been used for 60 seconds are terminated and removed from the pool.

Enable RADIUS Server

Select the checkbox to enable the integrated RADIUS Server. This option is enabled by default.

Default Shared Secret

Specify the default RADIUS shared secret. If specified, the RADIUS shared secret is used for any client that is not found in the RADIUS client configuration.

PingID Service ID

This setting should not be modified. The default value is vpn.

Application Name

Label to show on the PingID app’s authentication screen instead of the default text ("vpn").

Application Icon

Icon to show on the PingID app’s authentication screen instead of the default icon. The format of the graphic must be JPEG or PNG, and the graphic must be 100px x 100px or less, and 150 kB or less. The value of the parameter should be a valid URL that begins with https.

State Encryption Key

The base64 URL-encoded 256-bit key used to protect the integrity of the RADIUS state attribute. The RADIUS #24 State attribute is auto-generated by the PingID PCV and should not be modified. This parameter is unrelated to the State Attribute parameter in the previous table.

State Lifetime

The amount of time that the RADIUS server waits for a response before timeout (in seconds). The default value is 300.

Radius Client Doesn’t Support Challenge

The RADIUS client doesn’t support the access-challenge message in the RADIUS protocol. This mode also supports RADIUS clients which send the user collected OTP to the RADIUS server using the password field, for example Amazon Workspaces.

Supported authentication methods for this mode: Mobile App (Swipe, Biometrics, OTP), Desktop App, OATH tokens, Authenticator app and YubiKey.

Not supported: SMS, Voice and Email.

User experience:

  • If a mobile App user wishes to authenticate using swipe or biometrics, then OTP shouldn’t be entered in the RADIUS client password field.

  • If a mobile App user’s device is offline, then the user should enter the App generated OTP in the password field, after the password, using the separator defined in OTP in Password Separator.

  • If using the Desktop App or YubiKey, the user should enter the App or YubiKey generated OTP in the password field, after the password, using the separator defined in OTP in Password Separator.

  • If the user is registered with multiple devices supported by this mode, an OTP generated by any one of those devices will authenticate the user.

  • This mode does not support on-the-fly registration.

OTP in Password Separator

If the Radius Client Doesn’t Support Challenge is activated, and OTP fallback is enabled:

  • Comma: At login, users must enter their password followed by a comma, and then the OTP.

  • None: At login, users must concatenate the OTP to the end of their login password (without spaces, commas or any other separator).

Radius Client Password Validation

When the RADIUS client validates the user password, the RADIUS PCV will not get the password at all, and as a result, will not validate it. If the RADIUS client does not support the RADIUS challenge, the user’s OTP might be in the password field.

Direct OTP Validation

Perform OTP validation for RADIUS clients that do not support access-challenge and do not have a Delegate PCV configured.

PingID Username Attribute

The name of the attribute from the delegate PCV’s attribute contract that will be used as the PingID username for the RADIUS originated authentication.

PingID Heartbeat Timeout

The duration of time in seconds that the adapter will wait for the heartbeat calls to the PingID service, before falling back to the AUTHENTICATING DURING ERRORS feature. If left empty, the default is 30 seconds.

Newline Character

Select the line separation character that you want to use for RADIUS server challenge messages. Choose from:

  • None

  • Unix style ('\n')

  • Windows style ('\r\n")

  • HTML ('<br>')