Connectors

PingFederate Connector

Tap into the power of your existing PingFederate authentication policies by including them in your PingOne DaVinci flows.

A diagram of a DaVinci flow with a PingFederate authentication policy embedded in it.

The connector provides two ways to use PingFederate in your flow:

Redirectless method

The connector embeds the JavaScript Widget for the PingFederate Authentication API in your DaVinci flow. This lets you create a user experience that starts and stays in DaVinci without redirecting the browser.

  • The JavaScript Widget provides the user interface and communicates with the PingFederate authentication API.

  • Your PingFederate authentication policy can include any of the integrations on the widget compatibility list.

  • To tailor the user experience to match your DaVinci flow or company branding, you can customize the JavaScript Widget’s HTML, CSS, and JavaScript.

Redirect method

This method redirects the browser to PingFederate to complete an authentication policy. When the policy completes, PingFederate redirects the browser back to DaVinci.

  • The user interface is provided by an authentication application or adapter Velocity HTML templates, as configured in your PingFederate authentication policy.

  • Your authentication policy can include any component you want. You aren’t restricted to JavaScript Widget-compatible integrations.

  • You can customize these templates in PingFederate. For help, see Customizable user-facing pages and the integration-specific documentation.

With both methods, the PingFederate connector makes the following available in your DaVinci flow:

  • The access token

  • The refresh token

  • The ID token (decoded and encoded)

  • The complete (raw) response

Setup

Resources

For information and setup help, see the following:

Requirements

To use the connector, you’ll need:

  • A configured PingFederate environment

  • A configured PingFederate authentication policy

    If you want to use the redirectless approach, make sure your policy only includes adapters that are compatible with the PingFederate JavaScript Widget.

Setting up PingFederate

Enabling the authentication application programming interface (API)

Enable the authentication API if:

  • You want to use the connector with the redirectless (JavaScript Widget) method.

  • You want to use the connector with the redirect method and you want to use an authentication application in your PingFederate authentication policy.

    1. In PingFederate, go to Authentication → Integration → Authentication API Applications.

    2. Click Enable Authentication API.

    3. (Optional) If you’re using the redirect method and want to use an authentication application in your authentication policy, add an authentication application. For help, see Configuring authentication applications in the PingFederate documentation.

    4. Click Save.

    5. If you added an authentication application, select it in your authentication policy:

      1. Go to Authentication → Policies → Your policy.

      2. In the Authentication Application list, select your authentication application.

      3. Click Done.

Adding DaVinci as an OAuth client in PingFederate

  1. In PingFederate, go to Applications → OAuth Clients → Clients. Click Add Client.

  2. In the Client ID field, enter a unique ID, such as davinci-client. Note the ID. You’ll enter it in the connector settings.

  3. In the Client Name field, enter a name, such as DaVinci Client.

  4. For Client Authentication, select Client Secret.

  5. For Client Secret field, click Change Secret, then click Generate Secret. Note the secret. You’ll enter it in the connector settings.

  6. If you want to use the connector with the redirectless method, select Allow Authentication API OAuth Initiation.

  7. For Allowed Grant Types, select Authorization Code.

  8. (Optional) If you want to use refresh tokens, for Allowed Grant Types, select Refresh Token.

  9. For the OpenID Connect ID Token Signing Algorithm, select RSA using SHA-256.

  10. Click Save.

Configuring the PingFederate connector

Add the connector in DaVinci as shown in Adding a connector, then configure it as follows.

Connector configuration

Redirect URL

This connector’s redirect URL. If you use the connector with the redirect method, add this URL as a Redirect URI in your PingFederate OAuth Client configuration. This lets PingFederate redirect the browser back to this connector to continue the DaVinci flow. You don’t need this with the redirectless method.

lient ID

The client ID that you noted in Adding DaVinci as an OAuth Client in PingFederate.

Client Secret

The client secret that you noted in Adding DaVinci as an OAuth Client in PingFederate.

Scope

The scope requested from PingFederate, including openid. If you configured other scopes in your PingFederate. OAuth Client, add them here. Separate multiple scopes with a space.

Base URL

Enter your PingFederate base URL. For example, https://pf.example.com:9031.

Using the connector in a flow

Using the connector with the redirectless method

A screen capture that shows the complete flow.

  1. Download the PingFederate - Authentication (Redirectless) flow template. For help, see Using DaVinci flow templates.

  2. Select the Authenticate User (Redirectless) node.

    1. (Optional) If you have your own custom version of the PingFederate JavaScript Widget, enter the URL in the PingFederate JavaScript Widget URL field.

    2. (Optional) If you want to show your own logo on the PingFederate JavaScript Widget, enter the image URL in the PingFederate JavaScript Widget Logo URL field.

    3. (Optional) If you want to customize the page that will contain the PingFederate JavaScript Widget, edit the HTML Template, CSS, and Script fields. For information and tips, see Building a custom page in the HTTP connector documentation.

    4. Click Apply.

  3. Test the flow by clicking Save, Deploy, and Try Flow.

  4. Continue building your flow by replacing the Custom HTML Message node with a path to the resource that the user initially requested.

Using the connector with the redirect method

A screen capture that shows the complete flow.

The Authenticate User (Redirect) capability allows you to redirect the browser to PingFederate to allow the user to authenticate.

No special configuration is needed. Add the capability and populate its properties according to the help text.

Capabilities

Authenticate User (Redirectless)

Check username and password, perform account recovery, and other policy checks with the PingFederate AuthN API.

Show details
Properties
PingFederate JavaScript Widget URL textField required
PingFederate JavaScript Widget Logo URL textField
HTML Template textArea
CSS codeEditor
Script codeEditor
Authenticate User (Redirect)

Check username and password, perform account recovery, and other policy checks with PingFederate.

Show details
Properties
PingFederate Login button
Show "Powered by" Message toggleSwitch
Skip Button Press toggleSwitch