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.

Client 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)

Embed a PingFederate authentication policy in the DaVinci flow. The authentication policy can include components that work with the PingFederate JavaScript Widget.

Show details

  • Properties

  • Input Schema

  • Output Schema

PingFederate JavaScript Widget URL textField required

Default: https://s3.amazonaws.com/pingone/public_downloads/pingfederate/widget/latest/pf.authn-widget.js

PingFederate JavaScript Widget Logo URL textField
HTML Template textArea

Default:

<div class="content" style="padding: 30px">
 <div class="heading">Authentication Application</div>
 <form id="skForm">
 <input id="skinput-response" type="hidden" name="response" value=""/>
 <button data-skform="skForm" data-skbuttontype="form-submit" data-skbuttonvalue="submit" data-skvalue="submit" id="skbutton" data-skcomponent="skbutton" type="button" style="display:none"/>
 <div/>
 </button>
 </form>
 <div id="authnwidget">
</div>
CSS codeEditor

Default:

@import "https://assets.pingone.com/ux/end-user/0.36.1/end-user.css";
@import "https://s3.amazonaws.com/pingone/public_downloads/pingfederate/widget/latest/main-styles.css";
Script codeEditor

Write custom JavaScript. Caution: Custom code is for advanced users only. Before using custom code, review the security risks in the DaVinci documentation by searching for "Using custom code safely".

Default:

var script = document.createElement('script');
script.src = '{{widgetUrl}}';
script.onload = function () {
 load();
};
document.head.appendChild(script);

function load() {
 var authnWidget = new PfAuthnWidget("{{issuerUrl}}", {
 divId: 'authnwidget',
 logo: '{{widgetLogoUrl}}',
 });

 var config = {
 client_id: '{{clientId}}',
 scope: ['{{scope}}'],
 state: '{{state}}',
 response_type: 'code',
 onAuthorizationSuccess: function (response) {
 document.getElementById('skinput-response').value = JSON.stringify(response);
 document.getElementById('skbutton').click();
 },
 onAuthorizationFailed: function (response) {
 document.getElementById('skinput-response').value = JSON.stringify(response);
 document.getElementById('skbutton').click();
 },
 };
 authnWidget.initRedirectless(config);
}

  • default object

    • properties object

      • widgetUrl string required

        PingFederate JavaScript Widget URL

      • widgetLogoUrl string

        PingFederate JavaScript Widget Logo URL

      • customHTML string required

        HTML Template

      • customCSS string required

      CSS

      • customScript string required

    Script

  • output object

    • rawResponse object

      • access_token string

      • refresh_token string

      • id_token string

      • token_type string

      • expires_at number

    • statusCode number

    • headers object

    • sub string

    • aud string

    • jti string

    • iss string

    • iat number

    • exp number

    • auth_time string

    • tokens object

      • access_token string

      • refresh_token string

      • id_token string

      • token_type string

      • expires_at number

    • connectionId string

    • connectorId string

Authenticate User (Redirect)

Redirect to a PingFederate authentication policy, then return to the DaVinci flow. The authentication policy can include any components you want.

Show details

  • Properties

  • Output Schema

Display Name button
Show "Powered by" Message toggleSwitch
Skip Button Press toggleSwitch

  • output object

    • sub string

    • aud string

    • jti string

    • iss string

    • iat number

    • exp number

    • auth_time string

    • tokens object

      • access_token string

      • refresh_token string

      • id_token string

      • token_type string

      • expires_at number

    • connectionId string

    • connectorId string