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, it's 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