PingAuthorize

Configuring Apigee for PingAuthorize integration

In order for Apigee to use PingAuthorize as an external policy runtime service, you must install the PingAuth Shared Flow and configure Apigee.

Adding the PingAuthorize Shared Flow to Apigee

About this task

To install the PingAuth Shared Flow bundle in Apigee and configure it to integrate with PingAuthorize:

Steps

  1. Create a new bundle:

    Choose from:

    • For Apigee X, go to Develop > Shared Flows and click Upload Bundle.

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

  2. Upload the PingAuth Shared Flow bundle .zip file and name the shared flow PingAuth.

  3. Configure the connection to PingAuthorize:

    Choose from:

    • Apigee X

      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. Go to Develop > Shared Flows > PingAuth.

      2. On the Develop tab, select the latest revision in the Revisions list.

      3. In the Policies list, select the Load KVM Config policy.

      4. Remove the comment characters above and below the InitialEntries element in the policy editor panel.

      5. Edit the value for service_host_port to match the host name of your PingAuthorize server 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 value of the shared secret that you created in PingAuthorize.

      7. Click Save.

        Your finished configuration should look like this:

        Screen capture of the Apigee X key value map configuration for the PingAuth Shared Flow

    • Apigee Edge and Apigee Private Cloud

      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. Use the key name service_host_port and set the value to match the host name of your PingAuthorize server and the port of the HTTPS connection handler. For example, pingauthorize:8443.

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

      5. Click Save.

        Your finished 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 is configured to only trust the PingAuthorize HTTPS connection handler certificate if it is issued from a well-known certificate authority. To enable Apigee to trust specific HTTPS certificates from PingAuthorize servers:

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

    2. Give the keystore a name that helps you identify your PingAuthorize environment. For example, PingAuthorize-dev-truststore.

    3. Click the button to add a certificate. Enter a certificate alias and upload the certificate that is configured for the HTTPS connection handler in PingAuthorize. Click Save.

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

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

    5. Name the new reference PingAuthTrust. Select the keystore that you created previously, and then click Save.

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

    6. Go to Develop > Shared Flows > PingAuth.

    7. On the Develop tab, select the latest revision in the Revisions list.

    8. In the Policies list, select the Sideband Call policy.

    9. Remove the comment characters surrounding the TrustStore element in the policy editor panel, and then click Save.

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

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

Adding an API proxy in Apigee

About this task

To 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, complete the Name, Base path, and Target (Existing API) fields.

    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

    If you need to add an OAuth flow to your API proxy, complete these steps, and then see Configuring an OAuth flow in Apigee (optional).

  4. Select your deployment environment.

    Screen capture of the Apigee API proxy deployment environment option

  5. Click Create and Deploy.

Configuring an OAuth flow in Apigee (optional)

Before you begin

You must add an API proxy in Apigee.

About this task

This task only applies if you want to add OAuth authentication to the API proxy in Apigee. If you don’t want to add an OAuth flow, proceed to Attaching the PingAuthorize Shared Flow to API proxies.

These steps reference the Apigee Edge documentation. As you proceed, use values that correspond to you and your Apigee environment instead of the suggested example values. If needed, consult the Apigee X documentation.

Steps

  1. Create an .apigee.com/api-platform/tutorials/secure-calls-your-api-through-oauth-20-client-credentials//[API product]:

    1. Optional: Add scopes to the Allowed OAuth scopes field.

  2. Create a .apigee.com/api-platform/tutorials/secure-calls-your-api-through-oauth-20-client-credentials//[developer and an app].

    You can ignore the steps referring to the Key and Secret.

  3. Create an API proxy to generate an access token:

    1. Go to API Proxies > Create Proxy and click the No target tile.

    2. On the Proxy details page, enter /token in the Base path field.

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

      You will configure the OAuth authentication in another step.

  4. Add the OAuth policy to the token proxy:

    1. In the Policies list on the Develop tab of the token proxy, click the icon to add a policy.

    2. In the Security section, select the OAuthV2 policy.

    3. In the policy editor panel, add and define at least one custom attribute for your access token using the <Attribute> element inside of the <Attributes> element.

      Example:

      You must use one of the custom attributes added in this step to provide a value to the sub attribute in the PingAuth Shared Flow. The following example specifies the username attribute, but you can specify any custom attribute defined in this step.
      Screen capture of the OAuthV2 policy on the API Proxies page, with the custom attribute

  5. Map a custom attribute value to the value of the sub attribute:

    1. Open the PingAuth Shared Flow in Apigee.

    2. In the Resources list, select the Prepare-Request.js file.

    3. Uncomment this line:

      validated_access_token_values["sub"] = context.getVariable('accesstoken.{custom_attribute}')

    4. Replace {custom_attribute} with the value of a previously defined custom attribute.

      Example:

      Screen capture of the Prepare-Request.js editor window for the PingAuth Shared Flow, with the username attribute mapped to sub

  6. Configure Apigee to validate the access token:

    1. Read the oauth_flow/Readme document in the Ping Identity GitLab repository.

    2. Download the VerifyAccessToken and GetOAuthInfo files.

    3. In the API proxy hosting the PingAuth Shared Flow, add GetOAuthv2Info and VerifyAccessToken as policies.

    4. Select PreFlow in the Proxy Endpoints list.

    5. In the policy editor, before the PingAuth Shared Flow call, add a step for the GetOAuthv2Info policy.

    6. In the policy editor, before the GetOAuthv2Info policy call, add a step for the VerifyAccessToken policy.

      After configuration, the API proxy should look like the following:

      Screen capture of the API proxy with the PingAuth Shared Flow configured with token policies as specified

Result

Apigee issues and verifies the OAuth access token before launching the API proxy flow containing the PingAuth Shared Flow. The PingAuth Shared Flow is configured to pass the access token, when present, in the payload of the sideband request to PingAuthorize.

Passing the access token to the sideband endpoint using the request payload takes precedence over passing the token using the authorization header.

Attaching the PingAuthorize Shared Flow to API proxies

About this task

To 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. Click the icon to add a policy to the Policies list.

    3. In the Extension section, click Flow Callout.

    4. Select PingAuth from the Shared Flow list. Enter a policy name and then click Add.

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

  2. Attach the Flow Callout policy to flows.

    Because PingAuthorize typically provides fine-grained authorization, you should integrate PingAuthorize late in the PreFlow of the request to the proxy endpoint, after the coarse-grained authentication and authorization functions. See the Apigee documentation for more information on integrating PingAuthorize.

    1. In the Proxy Endpoints list on the left navigation pane, select PreFlow, and then click Step in the Request section to add a flow step to the request.

      Screen capture of the Apigee proxy endpoint PreFlow step creation

    2. On the Existing tab of Policy instance, select the Flow Callout policy that you created previously and click Add.

      Screen capture of the Apigee proxy endpoint PreFlow step configuration details

    3. In the Target Endpoints list on the left navigation pane, select PreFlow, and then click +Step in the Response section to add a flow step to the response.

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

    4. On the Existing tab of the Policy instance, select and add the previously created Flow Callout policy.

  3. Save and deploy the updated proxy.

    Screen capture of Apigee target endpoint PreFlow step configuration

Next steps

Configure fine-grained authorization policies in your PingAuthorize Policy Editor. To understand how to target specific API requests and extract other HTTP metadata to use in your policies, see Sideband API policy requests.