This procedure describes the process of creating and configuring a PingID SDK adapter for the purpose of providing pairing and authentication solutions integrated with PingFederate.
- PingFederate 8.2+
- If your installation should support integration with the PingFederate
Authentication API, the following minimum software versions are required:
- PingFederate 9.3+
- PingFederate PingID SDK IDP Adapter 1.7+
- The admin console UI menu labels in this document are those used in PingFederate 9.0. These may differ slightly from earlier versions of PingFederate.
The creation and configuration of an adapter comprises 3 mandatory steps:
- Create and configure a selector or tracked HTTP parameter
- Create and configure an adapter
- Create and configure a policy
- Configure proxy settings (requires PingFederate PingID SDK IDP Adapter 1.4+)
- HTML Form Adapter QR code button - passwordless login
-
Add a CANCEL button
to the QR code based authentication flowsNote:
- QR code based authentication requires PingFederate 9.2+ and PingFederate PingID SDK IDP Adapter 1.2+.
- QR code based authentication is not supported for the PF Authentication API.
Procedure:
-
Create and configure a selector or tracked HTTP parameter:
Create an instance of the PingID SDK Payload Handling Selector, which is required as a preprocessor to an authentication policy that uses the PingID SDK adapter.Important:
- PingFederate 9.1.x and below: Creation of a PingID SDK Payload Handling Selector is mandatory.
-
PingFederate 9.2+: Creation of a PingID SDK Payload Handling Selector
is not required, only if the "payload" parameter has
been added to PingFederate's Tracked HTTP Parameters (see https://support.pingidentity.com/s/document-item?bundleId=pingfederate-92&topicId=adminGuide%2Fpf_t_defineAuthenticationPolicies.html):
Identity Provider > AUTHENTICATION POLICIES > Policies > Tracked HTTP Parameters > Add:
payload
-
In the PingFederate admin console, select: Identity Provider > AUTHENTICATION POLICIES > Selectors.
-
Click Create New Instance to create a new
selector, or click on an existing selector to edit it.
The selector’s Type step is displayed.
-
All fields in the Type step are mandatory:
- INSTANCE NAME
- Enter a descriptive name for this selector.
- INSTANCE ID
- Enter a string which will be used as an ID for this selector. Spaces are not allowed.
- TYPE
- Select PingID SDK Payload Handling Selector from the dropdown options.
- Click NEXT.
- Click NEXT in the Authentication Selector screen.
- Click DONE in the Summary screen, to return to the Manage Authentication Selector Instances screen.
- Click SAVE to persist changes.
-
Create and configure an adapter:
-
In the PingFederate admin console, select: Identity Provider > APPLICATION INTEGRATION > Adapters.
The Manage IdP Adapter Instances screen is displayed.
-
Click Create New Instance to create a new
adapter, or click on an existing adapter to edit it.
The adapter’s Type step is displayed.
-
Enter the following fields in the Type
step:
- INSTANCE NAME
- Enter a descriptive name for this adapter.
- INSTANCE ID
- Enter a string which will be used as an ID for this adapter. Spaces are not allowed.
- TYPE
- Select PID SDK Adapter from the dropdown options.
- PARENT INSTANCE
- Leave this field with the default value: None.
-
Click NEXT to continue to the IdP
Adapter step.
-
Configure the following fields:
- PINGID SDK PROPERTIES
-
- Mandatory.
- Upload the PingID SDK properties file
from your PingOne admin console:
- In the PingOne admin console, go to Setup > PingID > CLIENT INTEGRATION > INTEGRATE WITH PINGID SDK > SETTINGS FILE.
- Click Download. You may want to provide the file with a more meaningful name.
- If you use a proxy, note that the deprecated
configuration of the
pingidsdk_proxy_url
entry in the PingID SDK properties file is still supported.Configuration of an entry in the PingFederate run.properties file (see Configure proxy settings), is the preferred configuration.
Note: If entries are defined in both the PingFederate run.properties and the PingID SDK properties files, the definition in the PingID SDK properties file will take precedence.
Important: The PingID SDK settings file should not be confused with the PingID properties file.
- APPLICATION ID
-
- Mandatory.
- Enter the application ID that was generated by
PingID SDK in your application configuration:
- In the PingOne admin console, go to Applications > PingID SDK Applications, and copy the Application ID.
Note:- From PingFederate 8.4 and PingFederate PingID SDK IDP Adapter 1.2, multiple applications can be linked to a single PingID SDK adapter for PingFederate. This is achieved with dynamic parameters overriding the value of Application ID. Refer to Dynamic parameters support in the PingID SDK developers guide for further details.
- In earlier versions of PingFederate and the PingID SDK Adapter, each application requires its own separate PingID SDK adapter for PingFederate.
- DEVICE PAIRING
-
- Choose how users will pair their first
device when it's a mobile device:
-
Automatic
(default).
Once authorization of the adapter completes successfully, the automatic pairing process begins.
-
Manual.
Once authorization of the adapter completes, the pairing process is not initiated. The pairing process is initiated separately. Depending on the UNPAIRED USERS - MANUAL PAIRINGBypass field configuration, the user will be allowed into the application or denied access.
-
Automatic
(default).
- Choose how users will pair their first
device when it's a mobile device:
- UNPAIRED USERS - MANUAL PAIRING
-
- Relevant only when Manual pairing is selected:
- Choose whether to allow users without a paired device to Bypass Authentication (default), or Block User - Require Pairing a device before continuing.
- UNPAIRED USERS - WEB LOGIN
- Choose whether to allow users without a paired device to Bypass Authentication (default), or Block User - Require Pairing a device before continuing, when signing in from a web platform.
- ADDITIONAL TRUSTED DEVICES
- When a user who already has a paired device, is pairing an additional device, choose whether to allow the user to approve pairing of the new device using a device in their existing trusted devices network and Verify New Devices with Primary Device (default), or to Pair Each Device Individually, without primary device verification.
- MFA TIMEOUT
- The duration of the PingID SDK MFA session with the adapter in minutes, before it times out and users need to authenticate again. (Default: 10 minutes, maximum 30 minutes.)
- USER VERIFICATION
- When the application setting VERIFY DEVICES
USING APPLE/ANDROID PUSH SERVICE is
enabled (in the PingOne admin console: Applications > PingID SDK Applications > [Application] > Configuration) and there is no approval for a silent
push sent for extra verification, choose whether to
Regard as Success or
Regard as Failure.Note: This configuration is relevant only to logins from mobile devices, and will be applied to pushless device scenarios, and events when the network is not accessible.
- AUTHENTICATION DURING ERRORS
- If there are network problems or the PingID SDK service is unreachable, choose whether to Bypass users (default) or Block users who attempt to authenticate.
- HEARTBEAT TIMEOUT
- The duration in seconds that the PingID SDK adapter should wait for a heartbeat to verify PingID SDK services, before timing out (default 30 seconds).
-
Click Advanced fields.
The advanced fields are displayed.
-
Configure the following fields:
- HTML TEMPLATE
-
Note: This field is relevant only when the PF Authentication API is not used.
- The name of the HTML template file whose screens are displayed to the user during the adapter authorization flow.
- The default is pingid.sdk.login.template.html. This default value is applied even if this field is left empty.
- Templates are located at /server/default/conf/template.
- MESSAGE FILE
-
- The prefix of the name of the PingID SDK messages file.
- The default is pingid-sdk-messages. This default value is applied even if this field is left empty.
- Templates are located at /server/default/conf/language-packs.
- The file prefix (for example pingid-sdk-messages) may be changed, but the suffix for the locale must be in the format “_<locale>.properties”, for example: pingid-sdk-messages_en.properties.
- CHANGE DEVICE
-
Note: This field is relevant only when the PF Authentication API is not used.
- Choose whether the CHANGE
DEVICE flow is allowed or denied.
- Allow (default): Users will see the CHANGE DEVICE button on all relevant screens.
- Deny: Users will not see the CHANGE DEVICE button, and will not have this option as part of their authentication flow.
- Choose whether the CHANGE
DEVICE flow is allowed or denied.
- SUCCESS SCREENS
-
Note: This field is relevant only when the PF Authentication API is not used.
- Choose whether to present the SUCCESS SCREENS as part of the authentication flow.
- Default: Show to Users.
- ERROR SCREENS
-
Note: This field is relevant only when the PF Authentication API is not used.
- Choose whether to present the ERROR screens as part of the authentication flow.
- Default: Show to Users.
- TIMEOUT SCREENS
-
Note: This field is relevant only when the PF Authentication API is not used.
- Choose whether to present the TIMEOUT screens as part of the authentication flow.
- Default: Show to Users.
- QR CODE BASED AUTHENTICATION
- Note: QR code based authentication is not supported for the PF Authentication API.Choose whether to use QR code based authentication, and in which cases:
- Disable (default).
- Conditionally enable: The QR code is displayed only when the user is unknown.
- Always enable: Allows QR code based authentication, whether the user is known or not.
- Default: QR code based authentication is the default authentication method, and the QR code is presented by default to the user.
Note:- The Default setting overrides the DEVICES SELECTION setting in the PingID SDK Applications Configuration in the PingOne admin web portal.
- QR code based authentication is supported from PingFederate 9.0. Note that PingFederate PingID SDK IDP Adapter 1.2 will work on versions earlier than 9.0 only when QR CODE BASED AUTHENTICATION is set to Disable. Attempting to save QR CODE BASED AUTHENTICATION using a setting other than Disable on versions of PingFederate earlier than 9.0 will result in the error message.
- ROOTED/JAILBROKEN DEVICE
-
- When an authentication device is identified as rooted or jailbroken:
- Allow: Allow the authentication flow to continue.
- Block (default): Deny the authentication request.
- When an authentication device is identified as rooted or jailbroken:
-
Click NEXT to continue to the
Extended Contract step.
The contract fields are displayed. In addition to the username attribute, the Core Contract also displays the following attributes:
- pingid.sdk.status holds information about the level of authentication through which the user was authenticated. For further information about this attribute, refer to PingFederate access token - pingid.sdk.status attribute in the PingID SDK developer guide.
- pingid.sdk.status.reason: Possible value is "device_rooted_or_jailbroken", which will appear only when the pingid.sdk.status has the value "pairing_error" and the device is rooted.
- authenticating.device.rooted: True or false.
- accessing.device.rooted: True or false.
-
Click NEXT to continue to the Adapter
Attributes step.
Check the Pseudonym checkbox for the username attribute.
- Click NEXT through each of the subsequent steps.
- Click DONE in the Summary step to return to the Manage IdP Adapter Instances screen.
- Click SAVE to persist changes.
Important: Adapter session considerationsIt is important to update the <pf_install>/pingfederate/server/default/conf/size-limits.conf file to adjust the session configuration to ensure that the PingID SDK adapter functions correctly.
Note that the settings in size-limits.conf are global, affecting all adapters.
-
In the PingFederate admin console, select: Identity Provider > APPLICATION INTEGRATION > Adapters.
-
Create and configure a policy:
Create a policy in PingFederate, for the purpose of determining the authentication flow.
The flexibility of PingFederate permits implementation of different policy models, and may vary according to organizational or application requirements.
The following example describes a basic policy configuration for the PingID SDK adapter, highlighting mandatory settings. The example defines a 1st factor authentication method before the SDK adapter, from which the username must then be mapped to the SDK adapter.
Important:- The SDK selector or Tracked HTTP Parameter:
- PingFederate 9.1.x and below: The PingID SDK Payload Handling Selector that was created earlier must be the first action in a policy actions chain.
- PingFederate 9.2+: The PingID SDK Payload Handling Selector is not required, only if the "payload" parameter has been added to PingFederate's Tracked HTTP Parameters (see https://support.pingidentity.com/s/document-item?bundleId=pingfederate-92&topicId=adminGuide/pf_t_defineAuthenticationPolicies.html).
- The SDK adapter created earlier must participate in the policy flow.
-
In the PingFederate administrative console, select: Identity Provider > AUTHENTICATION POLICIES > Policies.
The Manage Authentication Policies screen is displayed.
-
Enter the following fields:
- Check the ENABLE IDP AUTHENTICATION POLICIES checkbox.
- The SDK selector or Tracked HTTP Parameter:
-
PingFederate 9.1.x and below: The first
ACTION in the policy chain
must be mapped to the SDK selector created
earlier:
- Open the ACTION dropdown.
- Click IdP Adapters.
- Select the SDK selector.
- The SDK selector has only one return status:
Success.
For the policy's following action, select HTML Adapter (or any other 1st factor adapter) from the ACTION dropdown.
-
PingFederate 9.2+: If the "payload"
parameter has been added to PingFederate's Tracked HTTP Parameters
(see https://support.pingidentity.com/s/document-item?bundleId=pingfederate-92&topicId=adminGuide/pf_t_defineAuthenticationPolicies.html):
- Open the ACTION dropdown.
- Click HTML Adapter (or any other 1st factor adapter).
- Select the HTML Adapter.
-
PingFederate 9.1.x and below: The first
ACTION in the policy chain
must be mapped to the SDK selector created
earlier:
- The HTML Adapter has two resulting
states:
-
Fail:
The action following Fail will be Done, meaning the policy flow ends at this point.
-
Success:
Select the SDK Adapter for the action following Success.
-
Fail:
- Map the username from the HTML Adapter
(or any other 1st factor adapter) step in the policy flow to the
SDK Adapter:
- Click on Options below the SDK
Adapter.
The Incoming User ID screen opens.
- Source: Select HTML Adapter.
- Attribute: Select username.
- Click Done to return to the
Manage Authentication Policies
screen.
- Click on Options below the SDK
Adapter.
- An Authentication Policy Contract should then be mapped into the
target application (SP Connection, OAuth Grant Mapping, etc.)
for which you want to provide SSO services.
For example:
- Click Save.
- The SDK selector or Tracked HTTP Parameter:
-
(Optional) Configure proxy settings:
Define an entry in the PingFederate run.properties file, as described in the PingFederate admin guide (see https://documentation.pingidentity.com/pingfederate/pf/index.shtml#adminGuide/pf_t_configureForwardProxyServerSettings.html).Note: The native PingFederate method for defining a proxy is the preferred option. The following deprecated method is still supported:
- Manually add a
pingidsdk_proxy_url
entry to your PingID SDK properties file:pingidsdk_proxy_url=<your proxy address>
- Do not change the
pingidsdk_url
entry.
- Manually add a
-
(Optional) HTML Form Adapter QR code button - passwordless login:
Note:
- QR code based authentication requires PingFederate 9.2+ and PingFederate PingID SDK IDP Adapter 1.2+.
- QR code based authentication is not supported for the PF Authentication API.
QR code based authentication is an alternative method, which offers secure, passwordless authentication. QR code based authentication can effectively eliminate the need for first factor authentication. This method combines the strength of a strong secure authentication measure, with a streamlined user experience.
The following image presents the user HTML Form Adapter access screen. Once configured, the user can either use the traditional username and password sign on at the left, or select the Sign on with QR code button on the right. Sign on with QR code generates a QR code image which the user can scan with a trusted mobile device, thus achieving rapid secure passwordless authentication.
-
Refer to the Enable third-party identity providers
without registration topic in the PingFederate documentation,
specifically the following steps:
- Make a note of which authentication policy contract is currently being used in your policy.
- Create a local identity profile. Note: When creating the local identity profile, you must add "
QR Code
" as an Authentication Source. - Configure the HTML Form Adapter instance for customer identities.
-
Navigate to Identity Provider > Authentication Policies > Policies .
- In the Authentication Policies page, edit your PingID SDK authentication policy.
-
Below the HTML Form Adapter, expand the policy tree and select
Rules.
-
In the Rules popup, fill in the following
values:
Field Value Attribute Name policy.action
Condition equal to
Value QR Code
Result QR Code
- Click Done.
-
Below the HTML Form Adapter branch, the
QR CODE policy result is displayed, in
addition to the FAIL and SUCCESS branches.
-
In the QR Code result, select the SDK
Adapter, and finish building the flow according to the
steps in the Create and configure a policy section.
The final result should appear similar to the following image:
-
(Optional) Add a CANCEL button to the QR code based authentication
flows:
Note:There may be scenarios where an organization wants to allow users of QR code based authentication to cancel an authentication request. This can be achieved by configuring a CANCEL button in the QR based authentication flow, and defining its functionality in the authentication policy. By default, the CANCEL button is not enabled.
- QR code based authentication requires PingFederate 9.2+ and PingFederate PingID SDK IDP Adapter 1.2+.
- QR code based authentication is not supported for the PF Authentication API.
-
Configure a CANCEL Button in the HTML template:
- Open the HTML template file <PingFederate installation folder>/pingfederate-<version>/pingfederate/server/default/conf/template/pingid.sdk.login.template.html in a text editor.
- Scroll down to the QR Code section. You’ll see the
following commented out lines, where you can add a CANCEL button
in the QR image page, deep link page and loading
page:
<!-- uncomment the following line if you "cancel" is supported --> <!-- <a class="button" onclick="cancelQRCode(this)"href="javascript:void(0);">$messages.getMessage("pingid.sdk.authenticating.button.qrcode.cancel")</a>-->
- To add a CANCEL button to the page, uncomment the second line (containing the <a> tags).
-
Add a CANCEL function in the authentication policy:
- In the PingFederate admin console, navigate to Identity Provider > Authentication Policies > Policies .
- In the Authentication Policies page, edit your PingID SDK authentication policy.
- Below the SDK Adapter, expand the policy tree and
select Rules.
- In the Rules popup, fill in the
following values:
Field Value Attribute Name policy.action
Condition equal to
Value canceled
Result Fallback
(You may choose a different name.)
- Click Done.
- Below the SDK Adapter branch,
the FALLBACK policy result is displayed,
in addition to the FAIL and SUCCESS branches.
- To configure it as a restart flow action, select
Restart.Note: You can also choose different actions. For example, redirect the user to a different adapter.
- Click Done.
- Click Save.
- (Optional): If you want to change the action's default value
("canceled") to a different value:
- Go to the following line in the HTML
template:
<form id="cancelQRCodeForm" name="cancelQRCodeForm" action="$resumePath?cancel=1&action=canceled" method="post"> <input type="hidden" name="csrfToken" id="csrfToken" value="$csrfToken" encode="false"/> </form>
- Change
&action=canceled
to&action=<your value>
. Make sure that this new value is identical to the "Value" field in the Authentication Policies > Rules popup. - Click Done.
- Click Save.
- Go to the following line in the HTML
template:
- In the PingFederate admin console, navigate to Identity Provider > Authentication Policies > Policies .