Gateway changes

[stephenwf]

Originally for Madoc 1.x the expectation was that the infrastructure would set up a nginx and/or Cloudfront for both the Madoc site and also external APIs. This lead to a URLs that looked like this:

• my-site.com - The main site
• annotations.my-site.com - Annotation store
• manifests.my-site.com - IIIF APIs
• etc.

When starting on Madoc 2.x we wanted to simplify this further so that each external service instead had its own path on the same domain.

• my-site.com - The main site
• my-site.com/api/annotations - Annotations store
• my-site.com/api/iiif - IIIF APis
• etc.

This allowed us to reduce configuration and also swap out implementations seamlessly, so an API may start as a incubated project in another service and be split out on it's own later on. This also let us consolidate authentication. All API requests require an authenticated JWT, which is validated on each request.

Tyk.io was originally used to manage this routing. It was thought that this would speed up the development and ease configuration. However we ran into limitations with the configuration and ended up in a situation where we were working around the software, instead of with it.

Changes to the gateway

As of writing, these changes only apply to the release/2.0.0 branch and have not yet been published as new images.

The purpose of this discussion is to inform of the changes to the Gateway. To summarise the changes, we've switched from Tky (which uses to Nginx internally) to just Nginx. We've also changed how the RSA keypair is generated and managed and the "certs" image is no longer required.

Tyk to Nginx
The main change is the rewriting of the configuration from Tyk to plain Nginx. This has simplified the configuration, with most configurations simply being a definition of the path and proxy, with an optional authentication.

location /api/madoc {
    auth_request /_validate_jwt;
    proxy_pass http://madoc-ts:3000/api/madoc;
}

Previously there was a lot of boilerplate required for configurations, making it more difficult expand and less clear what all of the options meant.

If you want to add your own custom API, you can add a new my-service.conf that looks similar to the above and mount it into: /etc/nginx/conf.d/custom inside the gateway.

JWT validation
Previously Tyk handled verifying that the JWT was valid with the current RSA public key. However it was difficult to invalidate this key as it was stored in JSON on disk, and then loaded into the Tky database on startup. With the new Nginx, instead of validating the key within the gateway, we use an auth_request to validate the JWT. This lives within the madoc-ts service. The service runs a very small framework-less Node server that will validate incoming requests with Bearer tokens. For a user making a few requests in quick succession the auth responses are cached for 30 seconds.

Now that the madoc-ts is the owner of the RSA-keypair it is possible now to regenerate the keys, invalidating all user sessions. Previously any key generated would work until the key expired, even if the user was removed. This is a well-known trade off of using JWTs. However now we can add that extra invalidation for when it's required. This can be done from the Madoc admin when logged in as a user with the Global admin role.

Docker changes

If you are using a docker-compose.yml and upgrade to 2.0, your configuration should continue to work without changes. However the following are no longer required and can be removed:

• certs - The certs container is no longer required. This "sidecar" image generated the keypair on start up. This is now part of madoc as it's the only service that uses them. This includes any service that depends_on this service.
• Gateway environment variables - The following environment variables can be removed from the gateway service:
  • TYK_GW_STORAGE_HOST
  • TYK_GW_SECRET
  • JWT_SERVICES
• Gateway links - The gateway no longer needs to link to the redis. The gateway-redis can be removed from the links:
• Dependencies - All depends_on items can be removed. The gateway does not depend on any service.
• Volumes - The service no longer requires the /openssl-certs volume.