PingAuthorize

Configuring Apigee for PingAuthorize integration

Install the PingAuth shared flow bundle in Apigee and configure it to integrate with PingAuthorize.

Before you begin

Ensure you have:

  • A supported Apigee environment. The Ping Identity shared flow for Apigee supports Apigee Edge, Apigee Private Cloud, and Apigee X.

  • The PingAuth shared flow bundle .zip archive. Download the integration kit for Apigee from the Ping Identity Integration Directory.

Adding the PingAuthorize shared flow to Apigee

Steps

  1. Upload the shared flow bundle:

    1. In Apigee, go to Develop > Shared Flows and do one of the following:

      • In Apigee X, click Upload Bundle.

      • In Apigee Edge or Apigee Private Cloud, click +Shared Flow, and then click Upload Bundle.

    2. For the shared flow name, enter PingAuth.

    3. In File Picker, select the PingAuth shared flow bundle .zip archive.

    4. Click Create.

  2. In Apigee X, configure the connection to PingAuthorize.

    Skip this step if you’re using Apigee Edge or Apigee Private Cloud.

    Apigee X doesn’t support managing the configuration values stored in key-value maps through the Apigee UI. You must add these configuration values to the key-value map policy. The key-value map is created and the configuration values are added the first time the PingAuth shared flow executes at runtime.

    1. To access the PingAuth shared flow, go to Develop > Shared Flows > PingAuth.

    2. Click the Develop tab and examine Revisions to make sure you’re on the latest revision.

    3. In the Policies panel on the left, click the Load KVM Config policy.

    4. In the Code panel, remove the comment lines above and below the InitialEntries element.

    5. Edit the value for service_host_port to match the host name of your PingAuthorize server instance and the port of the HTTPS connection handler.

      For example, pingauthorize:8443.

      You can find the HTTPS connection handler port from the Configuration page of the PingAuthorize administrative console by going to System > Connection Handlers.

    6. Edit the value of shared_secret to match the shared secret that you created in PingAuthorize.

    7. Click Save.

      Your flow configuration should look like this:

      Screen capture of the Apigee X key-value map configuration for the PingAuth shared flow

  3. In Apigee Edge or Apigee Private Cloud, configure the connection to PingAuthorize.

    Apigee Edge stores environment-specific configuration values in key-value maps so that the same policies can be used across multiple deployment environments without any changes to the policies.

    1. Go to Environment > Key Value Maps and click +Key Value Map.

    2. Edit the key-value map and click Add Entry.

    3. Add a service_host_port key and set the value to the host name of your PingAuthorize Server instance and the port of the HTTPS connection handler.

      For example, pingauthorize:8443.

    4. Add a shared_secret key and set the value to the shared secret that you created in PingAuthorize.

    5. Click Save.

      Your key-value map configuration should look like this:

      Screen capture of the Apigee Edge and Private Cloud key-value map configuration for the PingAuth shared flow

  4. (Optional) Configure HTTPS trust for PingAuthorize.

    By default, the PingAuth shared flow only trusts the PingAuthorize HTTPS connection handler certificate if the certificate is issued from a well-known certificate authority. To enable Apigee to trust specific HTTPS certificates from PingAuthorize Server:

    1. Go to Environment > TLS Keystores and click +Keystore.

    2. Give the key store a name that helps you identify your PingAuthorize environment.

      For example, PingAuthorize-dev-truststore.

    3. Click the button to add a certificate.

    4. Enter a certificate alias and upload the certificate configured for the HTTPS connection handler in PingAuthorize.

      Screen capture of the TLS keystores page in Apigee with a PingAuth key store that contains the server certificate

    5. Click Save.

    6. Go to Environment > References and click +Reference.

    7. Name the new reference PingAuthTrust.

    8. Select the key store that you created previously and click Save.

      Screen capture of the Apigee References page after creating a PingAuthorize key store reference called PingAuthTrust

    9. Go to Develop > Shared Flows > PingAuth.

    10. On the Develop tab, examine Revisions to make sure you’re on the latest revision.

    11. In the Policies panel on the left, click the Sideband Call policy.

    12. In the Code panel, remove the comment characters surrounding the TrustStore element.

      Screen capture of the Apigee Sideband Call policy with the PingAuthTrust key store trust enabled

    13. Click Save.

  5. Go to Develop > Shared Flows > PingAuth and deploy the most recent revision to your environment.

Adding an API proxy in Apigee

Configure the API proxy in Apigee to point to the target endpoint that you want to reach.

Steps

  1. Go to API Proxies > Create Proxy and click the Reverse proxy tile.

    Screen capture of the Apigee API proxy creation menu

  2. On the Proxy details page, enter the Name, Base path, and Target (Existing API).

    Screen capture of the Apigee API proxy configuration details

  3. On the Common policies page, click Pass through (no authorization).

    Screen capture of the Apigee API proxy authorization options with Pass through (no authorization) selected in the Security: Authorization section

  4. Select the checkbox for your deployment environment.

    Screen capture of the Apigee API proxy deployment environment option

  5. Click Create and Deploy.

Attaching the PingAuthorize shared flow to API proxies

Attach the PingAuth shared flow to the API proxies where you want to use PingAuthorize as the external authorization policy runtime service.

Steps

  1. Add a Flow Callout policy:

    1. Go to one of your APIs in Develop > API Proxies and click the Develop tab.

      Ensure you are on the latest revision of the proxy.

    2. In the Policies panel on the left, click the icon.

    3. In the Add Policy modal, in the Extension panel on the left, click Flow Callout.

    4. Enter a Name for the policy.

      Screen capture of the Apigee Add Policy window for Flow Callout policy creation

    5. In the Shared Flow list, select PingAuth, and then click Add.

  2. Attach the Flow Callout policy to flows.

    Because PingAuthorize provides fine-grained authorization, you should integrate PingAuthorize late in the PreFlow of the request to the proxy endpoint, after coarse-grained authentication and authorization functions. Learn more about other ways to integrate PingAuthorize in Controlling API proxies with flows in the Apigee documentation.

    1. In the Proxy Endpoints panel on the left, click PreFlow.

    2. In the Request section, click +Step to add a flow step to the request.

      Screen capture of the Apigee proxy endpoint PreFlow step creation

    3. In the Add Step modal, click the Existing tab, and then select the Flow Callout policy you created previously.

      Screen capture of the Apigee proxy endpoint PreFlow step configuration details

    4. Click Add.

    5. In the Target Endpoints panel on the left, select PreFlow.

    6. In the Response section, click +Step to add a flow step to the response.

      This allows PingAuthorize to process the API response from the target API before it’s processed by Apigee.

    7. In the Add Step modal, click the Existing tab, and then select the Flow Callout policy you created previously.

  3. Save and deploy the updated proxy.

    Screen capture of Apigee target endpoint PreFlow step configuration

Next steps

Configure fine-grained authorization policies in the PingAuthorize Policy Editor. You can find information on how to target specific API requests and extract other HTTP metadata to use in your policies in Sideband API policy requests.