# API

The `gm-jwt-security` service uses the `ES512` signing algorithm for token generation.

## JWT Token Retrieval \[/policies]

To generate and retrieve a fully signed token, use the `/policies` endpoint. A request to this endpoint must have a header `userpolicyid`. To specify privileges to enable for the user payload, set the `privilege` parameters. If this is not set, all privileges will be dropped.

The service will search the Redis database for the `userpolicyid` value passed as a header. If the userpolicy is retrieved, the data is returned. Otherwise, if LDAP is configured, the LDAP server will be searched for this value in the `label` section of the user and this payload will be used for token generation. If LDAP is not configured, the `users.json` file will be searched in the same way. If the payload is empty or isn't found ,the request will fail with StatusForbidden.

The payload's privileges are then updated using the information passed in the `privilege` parameter. Any privileges that are not explicitly specified in this parameter are dropped from the payload.

The expiration for the token is created from the `TOKEN_EXP_TIME` environment variable, and the token is generated from the new payload, expiration date, and key value from `PRIVATE_KEY`. The original `userpolicyid`, the new token, and the expiration are set in the Redis database.

## JWT Token Generation and Redirect \[/tokens]

To generate a fully signed JWT token with a redirect, use the `/tokens` endpoint. Request parameters and their usage is as follows:

| Parameter   | Default        | Required | Description                                                     |
| ----------- | -------------- | -------- | --------------------------------------------------------------- |
| `user_dn`   |                | yes      | The user\_dn label used for searching for the user payload      |
| `redirect`  | ""             | yes      | the url to send the request redirect after generating the token |
| `path`      | `DEFAULT_PATH` | no       | the URLs over which the cookie will be sent                     |
| `minutes`   |                | no       | token expiration time in minutes                                |
| `seconds`   |                | no       | token expiration time in seconds                                |
| `privilege` |                | no       | privileges to use for payload                                   |

If the request contains a header `USER_DN` it will take precedence over the `user_dn` request parameter. If LDAP is configured, the LDAP server will be searched for this value in the `label` section of the user and the corresponding user payload will be used for token generation. If LDAP is not configured, the specified `users.json` file will be searched in the same way. If the payload is empty or isn't found, the request will fail with StatusForbidden.

The payload's privileges are then updated using the information passed in the `privilege` parameter. Any privileges that are not explicitly specified in this parameter are dropped from the payload.

The expiration for the token is created from the parameter `minutes` or `seconds`. If both are included in the request, the `minutes` value will take precedence. If neither are included, `TOKEN_EXP_TIME` is used.

The token is then generated using this payload, expiration date, and key value from the configured `PRIVATE_KEY`. A base64 `userpolicyid` is generated at random, and this `userpolicyid`, token, and expiration are set in the Redis database and an http cookie is created.

The `redirect` parameter tells the `gm-jwt-security` service where to send the original request with the new token once the token is generated. This allows for connection with `gm-data`. The request is then redirected to this url with the original request and generated token.

### Examples

The below examples assume that 'request header' includes `user_dn`.

* Privilege
  * By default, when a user payload is retrieved, its privileges are wiped out before token generation. To enable privileges on the user payload, the `privilege` parameter of the request must be specified. For example, if the user payload retrieved from an LDAP server or a `users.json` file contains `"privilege": [ "root", "readonly" ]`, the `"privilege"` field of the payload used for generating the token will be empty, but if the user wants to keep that privilege, then it can be requested in the url as `{BIND_ADDRESS}:{HTTP(S)_PORT}/token?redirect={redirect}&privilege=root`.
    * `localhost:18080/token?redirect=https://localhost:9443/services/gmdatax/2.0/html/1/&path=/services/&privilege=root`
* Path
  * The path over which the cookie can be sent can be specified using the `path` parameter
    * `localhost:18080/tokens?redirect=https://localhost:9443/services/gmdatax/2.0/html/1/&path=/services/`
* Expiration Date
  * Optionally the url can have `minutes` or `seconds` parameter which determines when the token will expire.
    * `localhost:18080/tokens?redirect=https://localhost:9443/services/gmdatax/2.0/html/1/&path=/services/&seconds=600`
    * `localhost:18080/tokens?redirect=https://localhost:9443/services/gmdatax/2.0/html/1/&path=/services/&minutes=10`