External OAuth provider with Microgateway

[Former Community Member]

Use Case

I have an external OAuth provider and I want to use microgateway to validate tokens issued by this provider.

Options

Modify edgemicro-auth

When using Microgateway, API consumers send a request to the token endpoint hosted on Apigee Edge. The token endpoint is served by the edgemicro-auth proxy (which is deployed when microgateway is configured). The edgemicro-auth proxy can be modified to make the call to the external OAuth token endpoint. If necessary, the externally generated token can also be stored in the JWT (as a claim) generated by the edgemicro-auth proxy. You can read details about how to configure the OAuth 2.0 policy to work with external auth providers here

1. There are no changes needed in microgateway.
2. The modified edgemicro-auth proxy (shipped by Apigee) needs to be kept in sync with updates.

Write a custom plugin

Writing a custom plugin is obviously an option. But there are a few tweaks recommended for this option. When using microgateway, it is recommended one uses JWT based access tokens (which is what Apigee does with the edgemicro-auth proxy). While we can debate in another article about pros and cons for using JWT vs Opaque tokens, JWT tokens are great for micrgoateway since the tokens can be validated without requiring a stateful, centralized server. So, writing a custom plugin to validate a JWT token is fairly trivial. What happens to analytics? One of the major values of microgateway is the fact that you get centralized analytics for all the APIs regardless of how many microgateways you have. When you don't use API keys or JWT tokens used by Apigee, microgateway cannot identify which application is consuming the API. Therefore, the analytics data sent to Apigee will be very limited (requests per second, latency, etc.).

What if I don't want to compromise? I want to use the external auth provider and I want FULL analytics. There is no free lunch. Apigee knows about API Products (which contains resource paths, proxies names etc.). These products are tied to Developer Apps. An external auth provider cannot tie a consumer (application) to an API product hosted in Apigee.

Here is a potential design:

Assumption 1

We assume the external auth provider is capable of issuing JWT based access tokens.

Assumption 2

The client_id for the application registered in the external auth provider is available in the JWT token. In fact, there is a standard (RFC7523) on how to pass a client_id as a JWT claim. That said, not everybody follows this standard. Take Azure of example. Azure includes the client_id in the azp (Authorized Party) claim. In the larger scheme of things, it doesn't matter where it is, as long as it is there. The next step is very important.

Import the external client_id to Apigee. Create a developer app in Apigee. Then use the steps documented here to import externally generated consumer keys and (optionally) secrets to Apigee. Associate one or more API Products with the app.

A sample plugin

This sample plugin here validates a JWT issued by Azure.

Extract the API Key

The custom plugin should extract the client_id from the JWT and add it to the request header.

//remove the azure header
delete (req.headers['authorization']);
		
//add client_id to header
req.headers['x-api-key'] = jwtdecode.payload[client_id];

Apigee Microgateway's OAuth plugin

Now add Apigee Microgateway's OAuth plugin in the plugin sequence (AFTER the custom plugin). Apigee's OAuth plugin is used for both OAuth and API Key verification. In this case, you can use it for API Key verification (that was added by the previous plugin).

A sample MG configuration file

  config_change_poll_interval: 600
  logging:
    level: error
    dir: /var/tmp
    stats_log_interval: 60
    rotate_interval: 24
  plugins:
    sequence:
      - azurejwt
      - oauth
...

oauth:
  allowNoAuthorization: false
  allowInvalidAuthorization: false
  keep-authorization-header: false
  allowAPIKeyOnly: true

Why Microgateway's OAuth plugin?

Analytics, analytics, analytics! We have an API key now. We want to validate it. That serves two purposes. The API Key will enforce some entitlements (i.e., which application has access to which API Product etc.) but will also be used by the analytics plugin to send application level analytics.

No customization of the edgemicro-auth proxy or the Apigee shipped plugins.