PingAuthorize

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.