PingAccess

Apigee API Gateway Integration

Ping Identity’s shared flow for Apigee extends Apigee’s authorization capabilities through an external authorization policy runtime service.

Integration with Apigee allows identity and access management (IAM) administrators to centrally manage access control and application protection in PingAccess, while enforcement is delegated to Apigee.

Use this guide to install and configure the shared flow in Apigee. After installation and configuration, you can manage access control rules, identity mappings, and other application protection features in PingAccess.

The following diagram shows how traffic flows through Apigee and PingAccess.

Diagram showing interactions between API clients, an Apigee API Gateway, , and an API target. The following list explains the interactions.

  1. The API client makes a request to the application programming interface (API) gateway.

  2. The shared flow extracts fields from the API client’s request and sends them to PingAccess for authorization.

  3. PingAccess evaluates the request, validates the authorization, then responds to Apigee. The response could be an authentication or authorization error that should be immediately sent back to the client, or it could be a modified request that Apigee will send to the API target.

  4. If authorized to proceed, Apigee passes the original or modified API request to the API target.

  5. The API service responds with the requested resource or with the result of the operation.

  6. The shared flow extracts fields from the API target’s response and sends them to PingAccess for processing.

  7. PingAccess responds to the processing request. The API response can be modified by the web session configuration and processing rules in PingAccess.

  8. Apigee responds to the API client with the original API response received from the API target or the modified response received from PingAccess.

Before you begin

The Ping Identity shared flow for Apigee supports Apigee Edge, Apigee Private Cloud, and Apigee X. Before you begin, ensure that you have the following:

  • A supported Apigee environment

  • PingAccess installed and started

  • The PingAuth shared flow bundle .zip file (sharedflowbundle.zip)

Configuring PingAccess for Apigee integration

About this task

Before Apigee can use PingAccess as an external authorization policy runtime service, you must prepare PingAccess to receive authorization requests from Apigee.

Steps

  1. Enable the Sideband service:

    1. Edit the <PA Home>/conf/run.properties file and set sideband.http.enabled=true.

    2. Optional: By default, PingAccess will listen for sideband clients on port 3020. You can choose a different port by editing the value of the sideband.http.port property.

    3. Restart PingAccess.

  2. Add a sideband client for Apigee:

    1. Go to Applications → Sideband Clients and click Add Sideband Client.

    2. Give the client a name that helps you identify the Apigee environment, such as Apigee-dev.

    3. Click Add Secret.

    4. Keep the header name of CLIENT-TOKEN unchanged, and copy the shared secret value.

      You will need this during the Apigee configuration.

    5. Click Save.

  3. Optional: Download the sideband listener HTTPS certificate.

    By default, the PingAuth shared flow is configured to only trust the PingAccess Sideband Listener HTTPS certificate if it is issued from a well-known certificate authority (CA). To trust specific HTTPS certificates for PingAccess servers:

    1. Go to Security → Key Pairs.

    2. Click the Pencil icon next to the key pair labeled SIDEBAND.

    3. Click Download Certificate and save the public key certificate. You will need this during the Apigee configuration.

Configuring Apigee for PingAccess integration

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

Steps

  1. Upload the shared flow bundle.

    Choose from:

    • If you are using Apigee X, go to Develop → Shared Flows and click Upload Bundle. Upload the PingAuth shared flow .zip file, and name the shared flow PingAuth.

    • If you are using Apigee Edge or Apigee Private Cloud, click Shared Flow, then click Upload Bundle. Upload the PingAuth shared flow bundle .zip file, and name the shared flow PingAuth.

    This screen capture shows the Create a Shared Flow window with the text PingAuth entered in the Name field.

  2. If you are using Apigee X, configure the connection to PingAccess.

    Unlike Apigee Edge, Apigee X doesn’t currently support managing the configuration values stored in key value maps in the Apigee interface. 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 is executed at runtime.

    1. Go to the PingAuth shared flow at Develop → Shared Flows → PingAuth.

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

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

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

    5. Edit the values for service_host_port and shared_secret to match the values that you obtained earlier.

    6. Click Save.

    This screen capture shows a completed Apigee X configuration. The service_host_port parameter is highlighted.

  3. If you are using Apigee Edge or Apigee Private Cloud, configure the connection to PingAccess.

    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. Use the key names service_host_port and shared_secret, and set the values to match the ones that you obtained earlier.

    3. Click Save.

    This screen capture shows a completed Apigee Edge or Apigee Private Cloud configuration on the Key Value Maps tab.

  4. Optional: Configure HTTPS trust for PingAccess.

    By default, the PingAuth shared flow is configured to only trust the PingAccess Sideband Listener HTTPS certificates if it is issued from a well-known CA. To trust specific HTTPS certificates for PingAccess servers:

    1. Go to the PingAuth shared flow at Develop → Shared Flows → PingAuth.

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

    3. In the Policies section of the Navigator, click the Sideband Call policy.

    4. In the policy editor panel, remove the comment characters surrounding the TrustStore element.

      Screen capture of the policy editor panel. The uncommented TrustStore element is highlighted.

    5. Click Save.

    6. Go to Environment → TLS Keystores and click Keystore.

    7. Give the key store a name that helps you identify your PingAccess environment, such as PingAccess-dev-truststore.

    8. Click to add a certificate, give the certificate an alias, and upload the certificate that you obtained earlier. Click Save.

      This screen capture shows a configured TLS keystore certificate.

    9. Go to Environment → References and click Reference.

    10. In the Name field, enter PingAuthTrust.

    11. Select the key store you created earlier, then click Save.

      This screen capture shows a configured PingAuthTrust reference.

  5. Deploy the shared flow:

    1. Go to Develop → Shared Flows → PingAuth.

    2. Deploy the most recent revision of the shared flow to your environment.

Adding an API Proxy in Apigee

Configure the API Proxy where you want to reach a target endpoint.

Steps

  1. Go to API Proxies → Create Proxy and click the Reverse Proxy tab.

  2. In the Name field, enter a name for the API proxy.

  3. In the Base Path field, enter the base path of the API.

  4. In the Target (existing API) field, enter the Uniform Resource Locator (URL) of the service invoked by the proxy.

  5. Click Next.

  6. In the Common Policies section, select Pass through (no authorization).

  7. Click Next.

  8. In the Optional Deployment section, select the deployment environment.

  9. Click Create and Deploy.

Attaching the PingAuth shared flow to API proxies in Apigee

Configure the PingAuth shared flow on the API proxies where you want to use PingAccess as the external authorization policy runtime service.

Steps

  1. Add a Flow Callout policy:

    1. In Develop → API Proxies, go to one of your APIs and click the Develop tab. Make sure that you are on the latest revision of the proxy.

    2. In the Policies section of the Navigator, click to add a policy.

    3. Add a Flow Callout Policy, and in the Shared Flow list, select PingAuth.

    4. Click Save.

    This screen capture shows the completed Flow Callout Policy on the Flow Callout tab of the Add Policy window.

  2. Attach the Flow Callout Policy to Flows.

    When PingAccess is integrated as the external authorization policy runtime service for Apigee, it should be integrated in the preflow of the request to the proxy endpoint, because the authentication and authorization function provided by PingAccess should occur before most other policies execute.

    You can consider other ways to integrate PingAccess by reading about flows at https://cloud.google.com/apigee/docs/api-platform/fundamentals/what-are-flows.

    1. In the Proxy Endpoint section of the Navigator, click PreFlow, then click Step to add a flow step to the request.

      This screen capture shows the included PreFlow step. PreFlow is highlighted.

    2. On the Existing tab, select the flow callout policy that you created, then click Add.

      This screen capture shows the Add Step window for the Flow Callout Policy.

    3. In the Target Endpoint section of the Navigator, select PreFlow, then add the flow callout policy as a Step to the Response flow.

      This gives PingAccess an early opportunity to process the API response from the target API before it is processed by Apigee.

      This screen capture shows the completed PingAuth policy.

  3. Save and deploy the updated proxy.

Creating an error handling policy in Apigee

About this task

When the target server returns an error, having an Apigee policy to handle that error prevents the API proxy from going into an error state in the target endpoint response and preventing the normal API proxy flow from continuing to the proxy endpoint.

Steps

  1. Add a policy with the AssignMessage type.

    A screen capture showing the Apigee policy with the AssignMessage type.

  2. Edit the target endpoint and add the new policy as a step in the default fault rule.

    For example:

    <DefaultFaultRule name="fault-rule">
     <Step>
          <Name>ReturnGenericError</Name>
     </Step>
</DefaultFaultRule>
    A screen capture showing the default fault rule with the new policy added as a step.

Configuring API applications in PingAccess

For each of the API proxies for which you attached the shared flow, configure a corresponding application in PingAccess.

About this task

The application is where you manage access control rules, identity mappings, and other application protection features. To add an API application, configure access validation, and configure Apigee as the application destination:

Steps

  1. Go to Applications → Applications and click Application.

  2. Enter a Name, and then enter the Context Root and select or create the Virtual Host(s) values to match how the application’s APIs are exposed from your Apigee environment.

    1. Optional: Click Create to create a new Virtual Host.

      This screen capture shows the top of a completed API application. The Name, Context Root, and Virutal Host(s) fields are filled out accordingly.

  3. In the Application Type list, select API.

  4. In the Access Validation list, select a form of access validation.

    A screen capture showing the Application Type field with API selected. Token Provider is selected in the Access Validation field.

  5. To configure Apigee as the application destination, in the Destination section, select Sideband, and then select the Sideband Client that you created earlier.

    A screen capture showing the configured Destination field, with Sideband selected as the destination and Apigee selected in the Sideband Client field.

  6. Click Save.

Supporting Web+API Applications

PingAccess simplifies adding OpenID Connect (OIDC) and OAuth to API-based web applications, such as single-page applications (SPAs).

About this task

In this configuration, PingAccess completely manages the OIDC authentication for the SPA, maintains a cookie-based web session with the browser, and replaces the cookie for an OAuth access token (or other identity mappings) before invoking the target API. You must perform additional steps to support this configuration.

Steps

  1. Configure Apigee to intercept calls for PingAccess.

    If you selected the Use context root as reserved resource base path check box on the PingAccess application you plan to use in conjunction with Apigee, skip ahead to step 2. When enabled, this feature provides reserved PingAccess resources from that application’s context root, which makes step 1 unnecessary.

    1. In Apigee, go to Develop → API Proxies and click Create New.

    2. On the Create Proxy page, click No Target.

    3. In the Name field, enter PingAccess.

    4. In the Base Path field, enter /pa.

      A screen capture showing the Proxy Details page with in the Name field and /pa in the Base path field.

    5. In the Policies section of the Navigator, click to add a policy.

    6. Add a Flow Callout Policy, and in the Shared Flow list, select PingAuth.

    7. Click Save.

    8. In the Proxy Endpoints section of the navigator, select PreFlow, then add the flow callout policy as a Request Step.

      A screen capture showing the Flow Callout Policy in the PreFlow tab.

    9. Save and deploy the new proxy.

  2. Add a Web+API application in PingAccess:

    1. Go to Applications → Applications and click Application.

    2. Enter a Name, and then enter the Context Root and select or create Virtual Host(s) values to match how the application’s APIs are exposed from your Apigee environment.

      To create a Virtual Host, click Create below the field name.
      A screen capture showing the top of the configured application. The Name, Context Root, and Virtual Host(s) fields are filled out accordingly.

  3. Configure the web session:

    1. In the Application Type list, select Web+API.

    2. Under Web Session, click Create.

    3. Enter the web session details, including the OIDC sign-on details configured in your OpenID Provider (OP).

      PingAccess can only manage the OIDC authentication on behalf of the browser if PingAccess, through Apigee, is configured as the redirect URL in your OIDC provider.

      For example, https://apigee.example.com/pa/oidc/cb.

    4. Click Save to save the web session.

    5. Under Web Identity Mapping, click Create.

    6. Name the identity mapping Access Token and select the type Web Session Access Token.

      This configures PingAccess to forward the OAuth Access Token it obtains from the OIDC provider Authorization Server as the bearer token to the API behind Apigee.

    7. Click Save.

      A screen capture showing the configured web session.

  4. In the Access Validation list, select the form of access validation that will be applied for non-web API clients, such as mobile applications.

  5. Configure Apigee as the application destination:

    1. In the Destination list, select Sideband.

    2. In the Sideband Client list, select the sideband client that you created earlier.

      A screen capture showing the Destination field with Sideband selected as the destination. Apigee is selected in the Sideband Client field.

    3. Click Save.