# JWT Security

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:

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

{% hint style="info" %}
**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.
{% endhint %}

#### Example

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

```bash
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](https://greymatter.gitbook.io/grey-matter-documentation/1.7-beta/reference/setup/fabric-1/grey-matter-jwt-security/ldap-configuration) as a backend server to search for user payloads.

{% hint style="info" %}
**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.
{% endhint %}

## Configure TLS

TLS can be configured on the `gm-jwt-security` service using [TLS Configuration](https://greymatter.gitbook.io/grey-matter-documentation/1.7-beta/reference/setup/fabric-1/grey-matter-jwt-security/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.

```bash
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

{% hint style="success" %}
**Need help configuring JWT?** Contact us at: [Grey Matter Support](https://support.greymatter.io/support/home).
{% endhint %}