Copyright (C) 2018 The Open Library Foundation
This software is distributed under the terms of the Apache License, Version 2.0. See the file "LICENSE" for more information.
Common/Shared library for Edge APIs.
The intent of edge-common is to simplify the implementation of edge APIs by providing much of the boilerplate code shared among these APIs.
This provides you with all the basics including configuration, initialization of secure store and token cache, etc.
Use InstitutionalUserHelper for common/shared tasks like parsing API keys, getting OKAPI tokens, etc.
Extend or use OkapiClient directly for making calls into FOLIO.
Other bits you may find helpful:
- A generic Cache class (See also: TokenCache and PatronIdCache)
- Mappers class containing static JSON/XML Mapper instances, common date formats, etc.
- A MockOkapi to facilitate mocking in unit tests.
- Commonly used Constants
Edge APIs should provide Module Descriptors which define their dependencies (e.g. on backend modules). Registering these module descriptors with OKAPI allows FOLIO's dependency management to be leveraged/extended to the edge APIs. See existing edge APIs for examples.
For now, some level of security is achieved via API Keys. Eventually we may want to implement a more sophisticated security model, e.g. based off of OAuth2, etc.
The API Keys used by the edge APIs are a URL safe base64 encoding of the three pieces of information:
- Salt - A random string of characters known only to the issuer of the API key, e.g.
- Tenant ID - A FOLIO tenant ID, e.g.
- Institutional Username - The username of the institutional user for this tenant. This could be the same as the tenant ID, or something else, e.g.
These components are then concatenated with an underscore delimiter
_ before being base64 encoded, e.g.
The final API Key looks something like:
The purpose of the salt is to prevent API Key from being guessed, which would be easy if the tenant ID was known, especially if the Institutional Username was the same as the tenant ID.
API Key Utilities
A utility class has been provided to help with API key generate, parsing, etc. The utility can be use programatically, or via a command line interface. Example CLI usage:
$ mvn package $ java -jar target/edge-common-api-key-utils.jar Usage: ApiKeyUtils [options] -g : generate an API Key (default: false) -p VAL : parse an API Key -s (--salt-len) N : the number of salt characters (default: 10) -t (--tenant-id) VAL : the tenant's ID -u (--username) VAL : the tenant's institutional user's username $ java -jar target/edge-common-api-key-utils.jar -g -s 20 -t diku -u diku QlBhb2ZORm5jSzY0NzdEdWJ4RGhfZGlrdV9kaWt1 $ java -jar target/edge-common-api-key-utils.jar -p QlBhb2ZORm5jSzY0NzdEdWJ4RGhfZGlrdV9kaWt1 Salt: BPaofNFncK6477DubxDh Tenant ID: diku Username: diku
API Key Sources
The API Key can be specified as either:
apiKeyquery argument, e.g.
Authorizationrequest header (see note below), e.g.
Authorization: apikey QlBhb2ZORm5jSzY0NzdEdWJ4RGhfZGlrdV9kaWt1
- As part of the URI path (denoted by
:apiKeyPathwhen defining routes in VertX), e.g.
This behavior is controlled by the
api_key_sources system property. The property takes a comma-separated list of sources; valid sources are
PATH. The order in which the sources are specified determines the order in which that source will be checked for the existance of an API key.
NOTE: There are two ways an API key may be provided by the
Authorization: apikey QlBhb2ZORm5jSzY0NzdEdWJ4RGhfZGlrdV9kaWt1(the auth type 'apikey' is case insensitive)
TIP: You can limit the API Key sources used by only listing those you want to check.
The idea here is that a FOLIO user is created for each tenant for the purposes of edge APIs. The credentials are stored in one of the secure stores and retrieved as needed by the edge API.
The Edge API does not create users, or write credentials. Those need to be provisioned manually or by some other process. The current secure stores expect credentials to be stored in a way that adheres to naming conventions. See the various secure store sections below for specifics.
Currently the institutional username is the same as the tenantId, but this is subject to change.
Three secure stores currently implemented for safe retrieval of encrypted credentials:
Only intended for development purposes. Credentials are defined in plain text in a specified properties file. See
Retrieves credentials from Amazon Web Services Systems Manager (AWS SSM), more specifically the Parameter Store, where they're stored encrypted using a KMS key. See
Retrieves credentials from a Vault (https://vaultproject.io). This was added as a more generic alternative for those not using AWS. See
Configuration information is specified in two forms:
- System Properties - General configuration
- Properties File - Configuration specific to the desired secure store
||Server port to listen on|
||required||Where to find Okapi (URL)|
||Type of secure store to use. Valid:
||Path to a properties file specifying secure store configuration|
||How long to cache JWTs, in milliseconds (ms)|
||How long to cache login failure (null JWTs), in milliseconds (ms)|
||Max token cache size|
||Log4j Log Level|
||Defines the sources (order of precendence) of the API key.|