okapi-auth-proxy -- old-style authentication for FOLIO

• Background
  • The problem
  • The solution
• Building okapi-auth-proxy
• Running okapi-auth-proxy
• Logging
• Security considerations
• Author
• License

okapi-auth-proxy provides a proxy for FOLIO's API gateway, Okapi, that implements the old and soon-to-be-deprecated login facilities and allows persistent tokens to be used. This is of value when running old scripts that rely on this method of authentication.

Background

The problem

The FOLIO library services platform is implementing refresh-token rotation. This will improve security, but at the cost of breaking lots of existing client code when the old-style permanent-token login facility goes away. Stripes-based UIs should continue to work, as the stripes-connect library has been updated to cope with the new regimen. But the many ad-hoc scripts used in operations will stop working.

The solution

okapi-auth-proxy accepts requests intended for a FOLIO instance. When it receives a request to log in at authn/login, it fulfils that request by instead using new login endpoint, remembering the short-lived tokens returned from that endpoint, and returns to the client an opaque long-lived token. Thereafter, every request make using that token is modified to send the corresponding short-lived token, and that token is transparently refreshed when necessary.

Building okapi-auth-proxy

You can install okapi-auth-proxy using the NMP package manager:

npm add okapi-auth-proxy
# Or to install globally
npm add -g okapi-auth-proxy

Or you can build it locally:

git clone https://github.com/indexdata/okapi-auth-proxy
cd okapi-auth-proxy
npm install

Running okapi-auth-proxy

Invocation is very simple: just run

okapi-auth-proxy

with no command-line arguments. The following options are supported:

• -p NUMBER or --port=NUMBER -- Listen on the specified port instead of the default of 3002.
• -V or --version -- Display the version number and exit
• -h or --help -- Display a full list of options

Clients send HTTP requests to the specified port, and the path that they use is the entire URL of the Okapi instance they want to be proxied to.

For example, a client wanting to use the FOLIO-snapshot Okapi service at https://folio-snapshot-okapi.dev.folio.org would connect to http://localhost:29168/https://folio-snapshot-okapi.dev.folio.org . The upshot is that an old script that previous worked by connecting to a FOLIO service that has converted to cookie-style authentication only can be made to work just by prefixing its Okapi URL with http://localhost:29168/.

The proxy can happily handle connections to multiple underlying Okapi services, whether they come from the same client or from multiple different clients.

Logging

This program uses the FolioJS library library to talk to the underlying Okapi services, and to handle FOLIO's new cookie-based authenticatoin. FolioJS in turn uses the tiny but beautiful categorical-logger library to provide optional logging. This is configured at run-time by the LOGGING_CATEGORIES or LOGCAT environment variable, which is set to a comma-separated list of categories such as login,auth. Messages in all the listed categories are logged.

The following categories of logging are supported by this program:

• listen: notes when the proxy is listening for requests
• login: notes when a client session logs in
• proxy: notes when a regular request is proxied on behalf of a client

In addition, the FolioJS library supports its own logging categories, of which auth and curl maybe be of particular interest: see the Logging section of its README.md for details.

Security considerations

okapi-auth-proxy drives a coach and horses through the security improvements introduced by FOLIO's refresh-token rotation. As such, access to a running proxy should be limited so that any leaked tokens cannot be used except within the protected context. Note that long-lived tokens are effectively expired when the proxy is started, so any concerns could be mitigated by periodically restarting the proxy.

Author

Mike Taylor, Index Data [email protected]

License

This software is provided under the terms of the Apache License version 2.0.