JWT Security

Configuration details for the Grey Matter JWT Security service.

You can deploy the Grey Matter JSON Web Token (JWT) Service many ways, including the following:

• The preferred approach is to deploy via a Docker container running inside of an OpenShift or Kubernetes Pod.

• The service is also packaged as a TAR file. The TAR contains an executable binary file you can deploy to a server.

Follow the configuration requirements below to set up the Grey Matter JWT Security service.

Prerequisites

Environment Variables

There are three required pieces of information to configure and run the service.

• Set JWT_API_KEY as an environment variable

• Set PRIVATE_KEY and USERS_JSON as a base64 encoded string, or as a volume mount (recommended)

• If both are provided, the volume mount supersedes the set variable

Variable	Mount Location	Default Value	Description	Type
JWT_API_KEY	-	""	base64 encoded string of comma separated api keys	base64
PRIVATE_KEY	/gm-jwt-security/certs/jwtES512.key	""	base64 encoded private key file	base64
USERS_JSON	/gm-jwt-security/etc/users.json	""	base64 encoded users.json file	base64

JWT_API_KEY is the base64 encoding of a comma separated list of API keys.

The users.json file should have a users field that contains an array of user payloads. This is an example:

{
  "users": [
    {
      "label": "CN=localuser,OU=Engineering,O=Decipher Technology Studios,=Alexandria,=Virginia,C=US",
      "values": {
        "email": [
          "[e-mail]"
        ],
        "org": [
          "www.deciphernow.com"
        ]
      }
    },
    {
      "label": "cn=chris.holmes, dc=deciphernow, dc=com",
      "values": {
        "email": [
          "[e-mail]"
        ],
        "org": [
          "www.deciphernow.com"
        ],
        "privilege": [
          "root"
        ]
      }
    }
  ]
}

Note: any service that provides the header api-key with a value matching one of the values in this list will have access to the /policies endpoint of the service, and can receive full jwt tokens.

Example

For the API key, list: 123,my-special-key,super-secret-key,pub-keyandJWT_API_KEY set to the value of:

echo "123,my-special-key,super-secret-key,pub-key" | base64 MTIzLG15LXNwZWNpYWwta2V5LHN1cGVyLXNlY3JldC1rZXkscHViLWtleQo=

Any service that provides the header api-key with a value matching one of the following will have access:

• 123

• my-special-key

• super-secret-key

• pub-key

Redis

The gm-jwt-security services creates and writes jwt tokens to a Redis server. In order to successfully generate and store jwt tokens, a Redis client must be implemented to connect to a server using information from the following environment variables.

Variable	Default Value	Description	Type
REDIS_HOST	"0.0.0.0"	host name of Redis server	string
REDIS_PORT	"6379"	port number of Redis server	string
REDIS_DB	0	Redis database to be selected after connecting to the server	uint
REDIS_PASS	"123"	password for Redis server	string

Optional Configuration

The following environment variables can be set to specify the host, ports, and logging capabilities of the gm-jwt-service. To specify an expiration time for generated tokens, set TOKEN_EXP_TIME.

Variable	Default Value	Description	Type
BIND_ADDRESS	"0.0.0.0"	bind address for the gm-jwt-security server	string
HTTP_PORT	8080	http port for the server	uint
HTTPS_PORT	9443	https port for the server	uint
ZEROLOG_LEVEL	"WARN"	logging level: INFO, DEBUG, WARN, ERR	string
TOKEN_EXP_TIME	28800	token expiration time in seconds	uint
DEFAULT_PATH	"/services/"	default path to apply to cookies generated by the /policies endpoint	string

Configure LDAP

The gm-jwt-security service supports LDAP as a backend server to search for user payloads.

Note: if LDAP is configured, it will take precedence over the users.json file. If LDAP is not configured, the configured USERS_JSON file will be searched for user payloads.

Configure TLS

TLS can be configured on the gm-jwt-security service using TLS Configuration.

Logging

The log level set by the ZEROLOG_LEVEL variable can be retrieved and dynamically changed via the following requests:

GET /logging

Returns the current log level.

current log level = info

PUT /logging?level=<log-level>

Updates the log level to the level indicated in query parameter level.

Level should be one of: error, warn, info, debug.

Questions

Need help configuring JWT? Contact us at: Grey Matter Support.