PingFederate Setup: End to End

This document provides an end-to-end overview of the process for setting up Akana API Platform support of PingFederate as an OAuth provider, and for testing the connection.

Note: This document addresses integration with PingFederate version 7.1.3.x. For information about later supported versions, see What versions of PingFederate does the platform support?

This is a high-level overview; individual procedures for completing the detailed setup steps are included in the user help and are not replicated here.

This document encompasses several roles, including:

  • PingFederate: Admin
  • Akana API Platform:
    • Akana System Admin
    • Business Admin / API Admin
    • Business Admin / App developer

One user might complete all steps, depending on the user's permission levels in PingFederate and in the Akana API Platform, or different steps might be completed by different users.

The table below lists all steps required, including the role, sequence, brief summary of actions, and a link to more detailed instructions.

Role Actions
Akana System Admin

You must have a working PingFederate installation, including installation of the Akana PingFederate Integration Add-on Feature (Plug-In). The Administrator must install the PingFederate plug-in on the following containers:

  • Network Director: All Network Director containers
  • Community Manager: All containers that have the OAuth Provider and CM APIs features installed.
PingFederate Admin

Makes sure PingFederate prerequisites are in place.

Determines which Akana API Platform domain type to use:

  • External OAuth Provider domain: Supports the Client Registration Endpoint. Recommended.
  • PingFederate domain: Legacy domain. Not recommended.
Akana System Admin

Sets up the PingFederate server certificate in Policy Manager.

Sets up an identity store for credentials needed by the PingFederate domain (recommended). See the Akana API Platform online help: Should I set up a platform identity, or provide the credentials in the domain configuration?
Akana API Platform Business Admin

Sets up PingFederate domain in the Akana API Platform:
Akana API Platform Business Admin or API Admin

Creates API in the Akana API Platform.

In implementation setup, choose:

  • Allow anonymous access: No
  • Choose OAuthSecurity policy

Akana API Platform online help: Adding an API and Managing API Implementations
Akana API Platform Business Admin or API Admin

In the OAuth Details wizard for the API, do the following:

  • Provider page: For OAuth Provider, choose the PingFederate domain set up by the Site Admin.
  • Resource Mapping page: Specify the resource mapping. The list of scopes defined in PingFederate is available for selection.

Akana API Platform online help: How do I configure OAuth Details for my API?

Note: If the scopes are not available, the connection with PingFederate is not working. Check the base URL, certificates, and other earlier steps. In PingFederate, the scopes are at this location: OAuth Settings > Authorization Server Settings.
PingFederate Admin

If you used the External OAuth Provider domain option, the steps below are not needed; clients are configured automatically when the contract between the app and the API is established in the Akana API Platform. Follow the steps below if you are using a legacy PingFederate Connector domain.

  1. Creates a client in PingFederate to represent the app we will create in the Akana API Platform in the next step.
    1. Choose OAuth Settings > Client Management.
    2. Click Add Client.
    3. For Client ID, choose a unique identifier for the app client ID; for example, PingValidationApp.
    4. For Client Secret, choose Generate Secret, and copy the secret for later use when setting up the app in the Akana API Platform.
    5. Choose a name.
    6. Under Redirection URIs, enter the base URL for your Akana API Platform installation, with /* after it. For example, if the base URL is https://www.acmepayments.com, enter https://www.acmepayments.com/* for the Redirection URI.
    7. Under Allowed Grant Types, choose Authorization Code (and others if needed).
    8. Save.
  2. Gives the Client ID and Client Secret values to the Akana API Platform Business Admin or app developer for setup of the app in the Akana API Platform.
Akana API Platform Business Admin or app developer

Creates app in the Akana API Platform.

For App Runtime ID and Shared Secret, enter the app client ID and Client Secret values received from the PingFederate Admin (see previous step).

Akana API Platform online help: Create an App.

Requests API access to the PingFederate API (fourth step above).

Akana API Platform online help: How do I get API access for my app?
Akana API Platform Business Admin or API Admin Approves API access for the app (Action Dashboard notification).
Akana API Platform Business Admin or app developer

Invokes the API in the Test Client:

  1. In the Akana API Platform, from the App Details page, click Test Client on the left menu.
  2. Choose the API and specify Sandbox or Live endpoint.
  3. Click the Security button, then click Get Token to access PingFederate and get an OAuth token.
  4. At the authentication popup, enter your credentials (and potentially approve requested grants).
  5. Verify that the token now appears in the Security window.
  6. In Test Client, click Invoke. The token is passed as an HTTP header in the request, and the API call is successful.

Akana API Platform online help: How do I test my app in Test Client?