Integrating Trusona with Ping Federate

How to use Trusona with Ping Federate standalone or as a composite adapter

What’s in this doc

Introduction

The Trusona Ping Adapter is an IdP adapter for Ping Federate that allows you to authenticate users with Trusona. It can be used standalone or as part of another composite adapter.

This adapter defines a contract that includes a field called user_identifer. When a user successfully authenticates, the adapter will fulfill the user_identifier with identifier established previously with the Trusona SDK. When using the Trusona App, user_identifier will be fulfilled with an email address matching the configured EMAIL_DOMAIN.

If you want to use the Trusona app and your own App with the Trusona SDK, we recommend you use an email address as the user_identifier so the contract will always be fulfilled with an email address as the user_identifer

In some situations, your entire user population may not be able to use Trusona. If so, this adapter will allow you to authenticate users with Ping’s built in Password Credential Validators. See the Advanced Configuration section of this guide for more information.

Prerequisites

This document assumes you have knowledge of how to configure Ping Federate for your specific needs. It is not intended to be used as a tutorial. For more guidance, see Get started with PingFederate Server 8.4.4

This adapter has been tested against PingFederate 8.4.4.

You will also need administrative access to your PingFederate installation.

Installation

To install, copy the Trusona Ping Adapter jar (trusona-ping-adapter-2.0.0.jar) into the pingfederate/server/deploy directory of your Ping Federate install. Additionally, copy the HTML template (trusona.form.template.html) into pingfederate/server/conf/template directory.

Optionally you may upload an image to use for branding of the hero section of the HTML template into pingfederate/server/default/conf/template/assets/images.

Afterwards, restart your PingFederate instance.

Configuration

  1. If you have not done so, log into the PingFederate administrative console.
  2. Click IdP Configuration on the Main Menu.
  3. Click Adapters under Application Integration Settings.
  4. On the Manage IdP Adapter Instances screen click Create New Instance.
  5. On the adapter Type screen, enter an Instance Name and Instance ID, select Trusona Adapter as the Type and click Next.
  6. Click Next.
  7. Enter your Trusona provided API Token and Secret in the Token and Secret fields.
  8. Enter a timeout value specifying how long to wait for the user to authenticate with Trusona. If you are unsure of what value to use, enter 90.
  9. If your PingFederate installation requires an HTTP proxy to reach Trusona, enter those details in HTTP_Proxy and HTTP_Port.
  10. Enter a domain name for Email Domain if you want to filter incoming email addresses from Trusona App users to a given domain.

Advanced Configuration

If you wish to enable the Trusona adapter to authenticate users with existing Password Credential Validators in addition to with Trusona, follow these steps.

  1. Click Add a new row to ‘Credential Validators’ to add a new row to the Credential Validators table.
  2. Select the Credential Validator to use with this adapter.
  3. Under User Identifier Attribute, enter the name of a field returned from the Password Credential Validator whose value will be used as the user_identifier in the adapter contract. For example, To use the mail attribute from an LDAP Credential Validator, enter mail.
  4. Click Update
  5. Repeat the above steps for any additional Password Credential Validators you may wish to configure.
  6. If you would like to direct users to a website when their password is expired, enter the URL for that site in PW_RESET_LINK
  7. If Trusona has enabled deep linking for your app, enter the provided URL in DEEPLINK_URL.
  8. If you have optionally uploaded an image to use for the hero section of the HTML template, enter that path into HERO_IMAGE, for example /assets/images/hero.jpg.

Composite Adapters

The Trusona adapter may be used as part of another composite adapter. If you wish to configure a built-in adapter as a fallback in the event the Trusona API is unavailable, add both the Trusona adapter and the built-in adapter to the composite, configuring them both to have the policy sufficient.