Token Authentication

Weave 2.6.8 includes builtin support for authenticating requests made to the server using tokens, specifically JSON Web Tokens. The addition of support for JWT is primarily aimed at allowing access to the Weave server from other servers, as opposed to a person using a web browser.

The generation of tokens is not enabled by default and relies on at least one configuration file, with the minimum requirement that a flag be set in that file to enable token generation support. The file is named token.properties and should be installed in the Weave workspace directory.

The Weave Admin UI provides a tool to allow generation of simple tokens that can be used by other servers to access Weave, but direct access to the API is also available if more complex tokens are required. There are currently two token generation endpoints, /weave/token/generate and /weave/token/generateToken, that need to be enabled individually.
The former end-point is the one exposed by the Admin UI and should be used to generate a token that can be generated and “installed” on another server and passed to Weave when requesting an action be performed by the Weave server (as the user encoded in the token).
Whereas the later end-point can be used by a user to generate a token for themselves. The later end-point is intended to be utilised for user authentication on things like mobile devices.

Below is a sample token.properties file outlining the available properties that can be set to configure the token generation and authentication.

# GENERATE ENDOINT

# Enable /generate endpoint. Defaults to false
generate.enable=true

# Only allow secure connections. Defaults to true.
generate.requireTls=true

# Require this role to allow token generation. Defaults to null (allowed for all authnticated users)
generate.userRole=ROLE_ADMIN_GENERATE_TOKEN


# GENERATE TOKEN ENDOINT

# Enable /generateToken endpoint. Defaults to false
generatetoken.enable=true

# Only allow secure connections. Defaults to true.
generatetoken.requireTls=true

# Require this role to allow token generation. Defaults to null (allowed for all authnticated users)
generatetoken.userRole=ROLE_GENERATE_TOKEN

# Default token duration. Defaults to 300
generatetoken.duration.default=300

# Max token duration. Defaults to value of generatetoken.duration.default
generatetoken.duration.max=600

# Filter the user's roles by regular expression. Defaults to null (all roles allowed)
# For example, to only allow roles that starts with "REST_", we set the value to: ^REST_.*
generatetoken.role.pattern=^REST_.*


# AUTHORIZATION

# A semi-colon separated list of paths and the roles required to access then
# E.g. authorization.roleFilters=/admin.*=ROLE_ADMIN;/admin/**=ROLE_ADMIN
# For fine grained control over the resources a token can access
authorization.roleFilters=/whoami/**=REST_ROLE

# A comma separated list of paths that are allowed for JWT auth
authorization.includePaths=/whoami,/services/*/entity/*,/services/**/edit/**,/services/**/form/list/**

# A comma separated list of paths that are not allowed for JWT auth
authorization.excludePaths=/**

# A Boolean indicating of includePaths should be checked before excludePaths
# This is to allow flexibility is how you want to restrict access to request paths, 
# depends on if you want to allow a lot of access then restrict it bit by bit, or 
# allow limited access and expand it bit by bit (the keycloak wiki page has more details)
# Defaults to false
authorization.includeBeforeExclude=true

# A comma separated list of trusted proxies ip addresses
# If you have a reverse proxy in front of Weave it should set a X-Forwarded-For header and be listed here
# Defaults to null
authorization.trustedProxies=


# SIGNING OPTIONS
# Settings for signing. If no signing settings are specified a default will be provided which provide s
# a uniqe key for each Weave instance (based on private.key)
# There are four providers available to chose from: password, secretkey, keypair and default.
# The provider is set by the property key "signing.provider"


# Password provider example
#signing.provider=password

# Required. Must be a strong password.
#signing.secret=aVeryStrongAndSecretPassword



# Secret key provider example
#signing.provider=secretkey

# Optional. Set algorithm [HS256,HS384,HS512]. Defaults to HS256.
#signing.algorithm=HS256

# Optional. File location of the secret key file. Defaults to workspace/jwt.key
#signing.location=/opt/weave/.jwt/jwt.key

# Optional. Is the content of the secret key file base64 encoded. Defaults to true.
#signing.base64=true

# Optional. Set the secret key content. The key must be base64 encoded. If set, the location and base64 properties will be ignored. Defaults to null.
#signing.secretkey=7g8vfq1ph5r7...Hk=



# Key pair provider example
#signing.provider=keypair

# Optional. Set algorithm [RS256,RS384,RS512,EC256,EC384,EC512]. Defualts to RS256.
#signing.algorithm=RS256

# Optional. File location of the private key file. Defaults to workspace/jwt.key
# A companion public key file will be created with the private key with a ".pub" extension. Defualts to workspace/jwt.pub
# I.e. for the setting below the public key location would be /opt/weave/.jwt/jwt.pub
#signing.location=/opt/weave/.jwt/jwt.key

# Optional. Is the content of the private and public key file base64 encoded. Defaults to true.
#signing.base64=true

# Optional. Set the private key content. The key must be base64 encoded. If set, the location and base64 properties will be ignored. Defaults to null.
# Note that the signing.publickey must be set for this setting to be used
#signing.privatekey=MIIJQQIBADANBgkqh...BCpExhJ9c0n/B9

# Optional. Set the public key content. The key must be base64 encoded. If set, the location and base64 properties will be ignored. Defaults to null.
# Note that the signing.publickey must be set for this setting to be used
#signing.publickey=MIICIjANBgkqhkiG9w...CAwEAAQ==