Google Apigee API Management OAuth Proxy

The OAuth Proxy is an extension to your API gateway that you need when your single page applications (SPAs) call OAuth-secured APIs using the Token Handler pattern. The SPA sends an encrypted proxy cookie that transports an access token. The OAuth Proxy plugin decrypts the cookie to extract the access token.

When the OAuth Proxy work completes, Google Apigee API Management routes the request to the target API, which uses the access token to implement its OAuth security.

Download the OAuth Proxy

You get the OAuth Proxy by downloading the latest ZIP file version from the Curity Developer Portal, with a filename of the following form.

curity-token-handler-proxy-apigee-<version>.zip

Unzip the downloaded file to get a shared flow ZIP file with the following filename format and a README with detailed deployment instructions:

sharedflow-<version>.zip

Deploy the OAuth Proxy

You must deploy the OAuth Proxy to a gateway that runs in your SPA's backend for frontend domain. If a deployment uses the following URLs, the OAuth Proxy executes in a gateway at https://bff.product.example:

• SPA Web Origin: https://www.product.example
• Backend for Frontend Base URL: https://bff.product.example
• Target API Base URL: https://api.example.com

To deploy the OAuth Proxy, upload the sharedflow-<version>.zip archive to your Apigee gateway and give it a name such as curity-token-handler.

Prepare Decryption

You need an asymmetric keypair as part of your overall token handler deployment. To create one, follow the instructions in the Configure Cryptographic Keys section of the Create a Token Handler tutorial. This results in a PKCS#8 file with an encrypted private key, and also a private key password.

Configure API Routes

You must configure the OAuth Proxy for all API routes that the SPA calls. Also, add a route such as /oauthuserinfo if the SPA calls the authorization server's OpenID Connect userinfo endpoint.

Start by creating a new policy of type FlowCallout using the name you created when uploading the OAuth Proxy:

<FlowCallout name="Token-Handler">
    <DisplayName>Curity Token Handler</DisplayName>
    <SharedFlowBundle>curity-token-handler</SharedFlowBundle>
</FlowCallout>

Then, configure a CORS Policy, to instruct the browser to allow requests with cookies from the SPA's web origin, and deny access to untrusted origins.

<CORS name="Cors">
  <AllowOrigins>https://www.product.example.com</AllowOrigins>
  <AllowCredentials>true</AllowCredentials>
</CORS>

Next, set input variables for to provide the cookie decryption key for the OAuth Proxy, using the content of the PKCS#8 file, and the PKCS#8 file's password. An example configuration using a Key Value Map is shown here:

<KeyValueMapOperations mapIdentifier="my-kvm" name="Set-Cookie-Key-From-KVM">
  <ExpiryTimeInSecs>1800</ExpiryTimeInSecs>
  <Scope>environment</Scope>
  <Get assignTo="tokenHandler.cookieKey" index="1">
    <Key>
      <Parameter>tokenHandlerCookieKey</Parameter>
    </Key>
  </Get>
  <Get assignTo="tokenHandler.cookieKeyPassword" index="1">
    <Key>
      <Parameter>tokenHandlerCookieKeyPassword</Parameter>
    </Key>
  </Get>
</KeyValueMapOperations>

Finally, configure the PreFlow of the ProxyEndpoint with all of the policies, with the CORS step expressed first:

<ProxyEndpoint name="default">
  <PreFlow name="default">
    <Request>
      <Step>
        <Name>Cors</Name>
      </Step>
      <Step>
        <Name>Set-Cookie-Key-From-KVM</Name>
      </Step>
      <Step>
        <Name>Token-Handler</Name>
      </Step>
    </Request>
    <Response>
    </Response>
  </PreFlow>
  <Flows>
    ...
  </Flows>
  ...
</ProxyEndpoint>

Additional configuration settings are also available. For example, if the OAuth Agent uses a different prefix for cookie names than the default value th-, you should configure a tokenHandler.cookiePrefix that matches the value from the OAuth Agent. You can find full information on how to manage configuration in the README file.

OAuth Proxy Output

At runtime, the OAuth Proxy processes cookies in incoming requests from SPAs. On success it rewrites the HTTP request, setting the access token in the HTTP authorization header. The target API then receives a JWT access token in the standard way and can use it for its authorization.

If the OAuth Proxy experiences an invalid cookie error, it returns an error response to the SPA with a 401 HTTP status code. For other types of error, the OAuth Proxy returns a 500 HTTP status code.

Conclusion

The OAuth Proxy is part of your API gateway. It enables your SPAs to use the correct browser security and also make direct calls to API URLs. The OAuth Proxy plugin deals with the cookie complexity so that you do not need to implement it in your API code.