Copyright (C) 2016-2022 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.
This module is responsible for filtering all proxy traffic and checking for a valid token. In addition, it is responsible for retrieving the permissions for a given user and making decisions regarding access based on user permissions and defined requirements for a given path. It provides a token creation endpoint that privileged modules (such as Authentication) may make use of.
Apache Maven 3.3.x or higher
mvn install java -jar target/mod-authtoken-far.jar
In addition to acting as a filter, the module exposes a few endpoints that are accessible as part as the regular Okapi ecosystem. These endpoints are as follows:
/token - This endpoint signs and returns an access token (JWT). It requires the permission auth.signtoken, which must be defined as a module permission to be used. It accepts a POST of a JSON object, with a field called payload that contains the claims of the token. The token is returned inside of a JSON object (response code 201), containing a field called token that has the token as a value.
/refreshtoken - This endpoint signs and returns a refresh token (JWE). It requires the permission auth.signrefreshtoken, which must be defined as a module permission. It accepts a POST of a JSON object, with required fields of userId and sub. The token is returned inside of a JSON object (response code 201), contained in a field called refreshToken.
/refresh - This endpoint takes a valid refresh token and returns a new access token. It accepts a POST of a JSON object, with required field refreshToken that contains the refresh token. It returns a new access token inside of a JSON object (response code 201), contained in a field called token.
The expiration time is hard-coded:
- 10 minutes for access tokens
- 24 hours for refresh tokens
MODAT-65 will make it configurable.
Command Line Options/System Properties
mod-authtoken supports a number of command line options as system properties, set by passing
-D<property.name>=<value> to the jar when loading.
jwt.signing.key- A passphrase to use as a signing key. If not set a random key is generated on each module restart invalidating all previously issued tokens. For clustering all instances of mod-authtoken must be configured to use the same key.
perm.lookup.timeout- Timeout for lookups to mod-permissions in seconds. Defaults to 10.
user.cache.seconds- Time to cache user permissions in seconds. Defaults to 60.
user.cache.purge.seconds- Time before a user is purged from the permissions cache in seconds. Defaults to 43200 (12 hours).
sys.perm.cache.seconds- Time that system permissions are cached in seconds. Defaults to 259200 (3 days).
sys.perm.cache.purge.seconds- Time before system permissions are purged from the permissions cache. Defaults to 43200 (12 hours).
log.level- Module log level.
port- Port the module will listen on. Defaults to 8081.
cache.permissions- Boolean controlling the permissions cache. Defaults to
Passing a value of "true" to the Authtoken-Refresh-Cache header for any request will inform mod-authtoken to delete the permissions cache for that userid and to request fresh permissions, regardless of cache age.
Other FOLIO Developer documentation is at dev.folio.org
See the ModuleDescriptor for the interfaces that this module requires and provides, the permissions, and the additional module metadata.
Generated API documentation.